]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/app.tex
cleanup
[wxWidgets.git] / docs / latex / wx / app.tex
1 \section{\class{wxApp}}\label{wxapp}
2
3 The {\bf wxApp} class represents the application itself. It is used
4 to:
5
6 \begin{itemize}\itemsep=0pt
7 \item set and get application-wide properties;
8 \item implement the windowing system message or event loop;
9 \item initiate application processing via \helpref{wxApp::OnInit}{wxapponinit};
10 \item allow default processing of events not handled by other
11 objects in the application.
12 \end{itemize}
13
14 You should use the macro IMPLEMENT\_APP(appClass) in your application implementation
15 file to tell wxWidgets how to create an instance of your application class.
16
17 Use DECLARE\_APP(appClass) in a header file if you want the wxGetApp function (which returns
18 a reference to your application object) to be visible to other files.
19
20 \wxheading{Derived from}
21
22 \helpref{wxEvtHandler}{wxevthandler}\\
23 \helpref{wxObject}{wxobject}
24
25 \wxheading{Include files}
26
27 <wx/app.h>
28
29 \wxheading{Library}
30
31 \helpref{wxBase}{librarieslist}
32
33 \wxheading{See also}
34
35 \helpref{wxApp overview}{wxappoverview}
36
37 \latexignore{\rtfignore{\wxheading{Members}}}
38
39
40 \membersection{wxApp::wxApp}\label{wxappctor}
41
42 \func{}{wxApp}{\void}
43
44 Constructor. Called implicitly with a definition of a wxApp object.
45
46
47 \membersection{wxApp::\destruct{wxApp}}\label{wxappdtor}
48
49 \func{virtual}{\destruct{wxApp}}{\void}
50
51 Destructor. Will be called implicitly on program exit if the wxApp
52 object is created on the stack.
53
54
55 \membersection{wxApp::argc}\label{wxappargc}
56
57 \member{int}{argc}
58
59 Number of command line arguments (after environment-specific processing).
60
61
62 \membersection{wxApp::argv}\label{wxappargv}
63
64 \member{wxChar **}{argv}
65
66 Command line arguments (after environment-specific processing).
67
68
69 \membersection{wxApp::CreateLogTarget}\label{wxappcreatelogtarget}
70
71 \func{virtual wxLog*}{CreateLogTarget}{\void}
72
73 Creates a wxLog class for the application to use for logging errors. The default
74 implementation returns a new wxLogGui class.
75
76 \wxheading{See also}
77
78 \helpref{wxLog}{wxlog}
79
80
81 \membersection{wxApp::CreateTraits}\label{wxappcreatetraits}
82
83 \func{virtual wxAppTraits *}{CreateTraits}{\void}
84
85 Creates the \helpref{wxAppTraits}{wxapptraits} object when \helpref{GetTraits}{wxappgettraits}
86 needs it for the first time.
87
88 \wxheading{See also}
89
90 \helpref{wxAppTraits}{wxapptraits}
91
92
93 \membersection{wxApp::Dispatch}\label{wxappdispatch}
94
95 \func{virtual void}{Dispatch}{\void}
96
97 Dispatches the next event in the windowing system event queue.
98
99 This can be used for programming event loops, e.g.
100
101 \begin{verbatim}
102 while (app.Pending())
103 Dispatch();
104 \end{verbatim}
105
106 \wxheading{See also}
107
108 \helpref{wxApp::Pending}{wxapppending}
109
110
111 \membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
112
113 \func{virtual void}{ExitMainLoop}{\void}
114
115 Call this to explicitly exit the main message (event) loop.
116 You should normally exit the main loop (and the application) by deleting
117 the top window.
118
119
120 \membersection{wxApp::FilterEvent}\label{wxappfilterevent}
121
122 \func{int}{FilterEvent}{\param{wxEvent\& }{event}}
123
124 This function is called before processing any event and allows the application
125 to preempt the processing of some events. If this method returns $-1$ the event
126 is processed normally, otherwise either {\tt true} or {\tt false} should be
127 returned and the event processing stops immediately considering that the event
128 had been already processed (for the former return value) or that it is not
129 going to be processed at all (for the latter one).
130
131
132 \membersection{wxApp::GetAppDisplayName}\label{wxappgetappdisplayname}
133
134 \constfunc{wxString}{GetAppDisplayName}{\void}
135
136 Returns the user-readable application name. The difference between this string
137 and the one returned by \helpref{GetAppName}{wxappgetappname} is that this one
138 is meant to be shown to the user and so should be used for the window titles,
139 page headers and so on while the other one should be only used internally, e.g.
140 for the file names or configuration file keys.
141
142 By default, returns the same string as \helpref{GetAppName}{wxappgetappname}.
143
144 \newsince{3.0}
145
146
147 \membersection{wxApp::GetAppName}\label{wxappgetappname}
148
149 \constfunc{wxString}{GetAppName}{\void}
150
151 Returns the application name.
152
153 \wxheading{Remarks}
154
155 wxWidgets sets this to a reasonable default before
156 calling \helpref{wxApp::OnInit}{wxapponinit}, but the application can reset it at will.
157
158 \wxheading{See also}
159
160 \helpref{GetAppDisplayName}{wxappgetappdisplayname}
161
162
163 \membersection{wxApp::GetClassName}\label{wxappgetclassname}
164
165 \constfunc{wxString}{GetClassName}{\void}
166
167 Gets the class name of the application. The class name may be used in a platform specific
168 manner to refer to the application.
169
170 \wxheading{See also}
171
172 \helpref{wxApp::SetClassName}{wxappsetclassname}
173
174
175 \membersection{wxApp::GetExitOnFrameDelete}\label{wxappgetexitonframedelete}
176
177 \constfunc{bool}{GetExitOnFrameDelete}{\void}
178
179 Returns true if the application will exit when the top-level window is deleted, false
180 otherwise.
181
182 \wxheading{See also}
183
184 \helpref{wxApp::SetExitOnFrameDelete}{wxappsetexitonframedelete},\\
185 \helpref{wxApp shutdown overview}{wxappshutdownoverview}
186
187
188 \membersection{wxApp::GetInstance}\label{wxappgetinstance}
189
190 \func{static wxAppConsole *}{GetInstance}{\void}
191
192 Returns the one and only global application object.
193 Usually \texttt{wxTheApp} is usead instead.
194
195 \wxheading{See also}
196
197 \helpref{wxApp::SetInstance}{wxappsetinstance}
198
199
200 \membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}
201
202 \constfunc{virtual wxWindow *}{GetTopWindow}{\void}
203
204 Returns a pointer to the top window.
205
206 \wxheading{Remarks}
207
208 If the top window hasn't been set using \helpref{wxApp::SetTopWindow}{wxappsettopwindow}, this
209 function will find the first top-level window (frame or dialog) and return that.
210
211 \wxheading{See also}
212
213 \helpref{SetTopWindow}{wxappsettopwindow}
214
215
216
217 \membersection{wxApp::GetTraits}\label{wxappgettraits}
218
219 \func{wxAppTraits *}{GetTraits}{\void}
220
221 Returns a pointer to the \helpref{wxAppTraits}{wxapptraits} object for the application.
222 If you want to customize the \helpref{wxAppTraits}{wxapptraits} object, you must override the
223 \helpref{CreateTraits}{wxappcreatetraits} function.
224
225
226
227 \membersection{wxApp::GetUseBestVisual}\label{wxappgetusebestvisual}
228
229 \constfunc{bool}{GetUseBestVisual}{\void}
230
231 Returns true if the application will use the best visual on systems that support
232 different visuals, false otherwise.
233
234 \wxheading{See also}
235
236 \helpref{SetUseBestVisual}{wxappsetusebestvisual}
237
238
239 \membersection{wxApp::GetVendorName}\label{wxappgetvendorname}
240
241 \constfunc{wxString}{GetVendorName}{\void}
242
243 Returns the application's vendor name.
244
245
246 \membersection{wxApp::IsActive}\label{wxappisactive}
247
248 \constfunc{bool}{IsActive}{\void}
249
250 Returns \true if the application is active, i.e. if one of its windows is
251 currently in the foreground. If this function returns \false and you need to
252 attract users attention to the application, you may use
253 \helpref{wxTopLevelWindow::RequestUserAttention}{wxtoplevelwindowrequestuserattention}
254 to do it.
255
256
257 \membersection{wxApp::IsMainLoopRunning}\label{wxappismainlooprunning}
258
259 \func{static bool}{IsMainLoopRunning}{\void}
260
261 Returns \true if the main event loop is currently running, i.e. if the
262 application is inside \helpref{OnRun}{wxapponrun}.
263
264 This can be useful to test whether events can be dispatched. For example,
265 if this function returns \false, non-blocking sockets cannot be used because
266 the events from them would never be processed.
267
268
269 \membersection{wxApp::MainLoop}\label{wxappmainloop}
270
271 \func{virtual int}{MainLoop}{\void}
272
273 Called by wxWidgets on creation of the application. Override this if you wish
274 to provide your own (environment-dependent) main loop.
275
276 \wxheading{Return value}
277
278 Returns 0 under X, and the wParam of the WM\_QUIT message under Windows.
279
280 %% VZ: OnXXX() functions should *not* be documented
281 %%
282 %%\membersection{wxApp::OnActivate}\label{wxapponactivate}
283 %%
284 %%\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}}
285 %%
286 %%Provide this member function to know whether the application is being
287 %%activated or deactivated (Windows only).
288 %%
289 %%\wxheading{See also}
290 %%
291 %%\helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent}
292 %%
293 %%\membersection{wxApp::OnCharHook}\label{wxapponcharhook}
294 %%
295 %%\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
296 %%
297 %%This event handler function is called (under Windows only) to allow the window to intercept keyboard events
298 %%before they are processed by child windows.
299 %%
300 %%\wxheading{Parameters}
301 %%
302 %%\docparam{event}{The keypress event.}
303 %%
304 %%\wxheading{Remarks}
305 %%
306 %%Use the wxEVT\_CHAR\_HOOK macro in your event table.
307 %%
308 %%If you use this member, you can selectively consume keypress events by calling\rtfsp
309 %%\helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in.
310 %%
311 %%\wxheading{See also}
312 %%
313 %%\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
314 %%\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
315
316
317 \membersection{wxApp::OnAssertFailure}\label{wxapponassertfailure}
318
319 \func{void}{OnAssertFailure}{\param{const wxChar }{*file}, \param{int }{line}, \param{const wxChar }{*func}, \param{const wxChar }{*cond}, \param{const wxChar }{*msg}}
320
321 This function is called when an assert failure occurs, i.e. the condition
322 specified in \helpref{wxASSERT}{wxassert} macro evaluated to {\tt false}.
323 It is only called in debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) as
324 asserts are not left in the release code at all.
325
326 The base class version shows the default assert failure dialog box proposing to
327 the user to stop the program, continue or ignore all subsequent asserts.
328
329 \wxheading{Parameters}
330
331 \docparam{file}{the name of the source file where the assert occurred}
332
333 \docparam{line}{the line number in this file where the assert occurred}
334
335 \docparam{func}{the name of the function where the assert occurred, may be
336 empty if the compiler doesn't support C99 \texttt{\_\_FUNCTION\_\_}}
337
338 \docparam{cond}{the condition of the failed assert in text form}
339
340 \docparam{msg}{the message specified as argument to
341 \helpref{wxASSERT\_MSG}{wxassertmsg} or \helpref{wxFAIL\_MSG}{wxfailmsg}, will
342 be {\tt NULL} if just \helpref{wxASSERT}{wxassert} or \helpref{wxFAIL}{wxfail}
343 was used}
344
345
346 \membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror}
347
348 \func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}}
349
350 Called when command line parsing fails (i.e. an incorrect command line option
351 was specified by the user). The default behaviour is to show the program usage
352 text and abort the program.
353
354 Return {\tt true} to continue normal execution or {\tt false} to return
355 {\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program.
356
357 \wxheading{See also}
358
359 \helpref{OnInitCmdLine}{wxapponinitcmdline}
360
361
362 \membersection{wxApp::OnCmdLineHelp}\label{wxapponcmdlinehelp}
363
364 \func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}}
365
366 Called when the help option ({\tt --help}) was specified on the command line.
367 The default behaviour is to show the program usage text and abort the program.
368
369 Return {\tt true} to continue normal execution or {\tt false} to return
370 {\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program.
371
372 \wxheading{See also}
373
374 \helpref{OnInitCmdLine}{wxapponinitcmdline}
375
376
377 \membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed}
378
379 \func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}}
380
381 Called after the command line had been successfully parsed. You may override
382 this method to test for the values of the various parameters which could be
383 set from the command line.
384
385 Don't forget to call the base class version unless you want to suppress
386 processing of the standard command line options.
387
388 Return {\tt true} to continue normal execution or {\tt false} to return
389 {\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program.
390
391 \wxheading{See also}
392
393 \helpref{OnInitCmdLine}{wxapponinitcmdline}
394
395
396 \membersection{wxApp::OnExceptionInMainLoop}\label{wxapponexceptioninmainloop}
397
398 \func{virtual bool}{OnExceptionInMainLoop}{\void}
399
400 This function is called if an unhandled exception occurs inside the main
401 application event loop. It can return \true to ignore the exception and to
402 continue running the loop or \false to exit the loop and terminate the
403 program. In the latter case it can also use C++ \texttt{throw} keyword to
404 rethrow the current exception.
405
406 The default behaviour of this function is the latter in all ports except under
407 Windows where a dialog is shown to the user which allows him to choose between
408 the different options. You may override this function in your class to do
409 something more appropriate.
410
411 Finally note that if the exception is rethrown from here, it can be caught in
412 \helpref{OnUnhandledException}{wxapponunhandledexception}.
413
414
415 \membersection{wxApp::OnExit}\label{wxapponexit}
416
417 \func{virtual int}{OnExit}{\void}
418
419 Override this member function for any processing which needs to be
420 done as the application is about to exit. OnExit is called after
421 destroying all application windows and controls, but before
422 wxWidgets cleanup. Note that it is not called at all if
423 \helpref{OnInit}{wxapponinit} failed.
424
425 The return value of this function is currently ignored, return the same value
426 as returned by the base class method if you override it.
427
428
429 \membersection{wxApp::OnFatalException}\label{wxapponfatalexception}
430
431 \func{void}{OnFatalException}{\void}
432
433 This function may be called if something fatal happens: an unhandled
434 exception under Win32 or a a fatal signal under Unix, for example. However,
435 this will not happen by default: you have to explicitly call
436 \helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions} to enable this.
437
438 Generally speaking, this function should only show a message to the user and
439 return. You may attempt to save unsaved data but this is not guaranteed to
440 work and, in fact, probably won't.
441
442 \wxheading{See also}
443
444 \helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}
445
446 %% VZ: the wxApp event handler are private and should not be documented here!
447 %%
448 %%\membersection{wxApp::OnIdle}\label{wxapponidle}
449 %%
450 %%\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
451 %%
452 %%Override this member function for any processing which needs to be done
453 %%when the application is idle. You should call wxApp::OnIdle from your own function,
454 %%since this forwards OnIdle events to windows and also performs garbage collection for
455 %%windows whose destruction has been delayed.
456 %%
457 %%wxWidgets' strategy for OnIdle processing is as follows. After pending user interface events for an
458 %%application have all been processed, wxWidgets sends an OnIdle event to the application object. wxApp::OnIdle itself
459 %%sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
460 %%their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
461 %%calling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWidgets will send another OnIdle
462 %%event to the application object. This will occur in a loop until either a user event is found to be
463 %%pending, or OnIdle requests no more time. Then all pending user events are processed until the system
464 %%goes idle again, when OnIdle is called, and so on.
465 %%
466 %%\wxheading{See also}
467 %%
468 %%\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
469 %%\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
470 %%
471 %%\membersection{wxApp::OnEndSession}\label{wxapponendsession}
472 %%
473 %%\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}}
474 %%
475 %%This is an event handler function called when the operating system or GUI session is
476 %%about to close down. The application has a chance to silently save information,
477 %%and can optionally close itself.
478 %%
479 %%Use the EVT\_END\_SESSION event table macro to handle query end session events.
480 %%
481 %%The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a true argument
482 %%(forcing the application to close itself silently).
483 %%
484 %%\wxheading{Remarks}
485 %%
486 %%Under X, OnEndSession is called in response to the `die' event.
487 %%
488 %%Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message.
489 %%
490 %%\wxheading{See also}
491 %%
492 %%\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
493 %%\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
494 %%\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
495
496
497 \membersection{wxApp::OnInit}\label{wxapponinit}
498
499 \func{bool}{OnInit}{\void}
500
501 This must be provided by the application, and will usually create the
502 application's main window, optionally calling
503 \helpref{wxApp::SetTopWindow}{wxappsettopwindow}. You may use
504 \helpref{OnExit}{wxapponexit} to clean up anything initialized here, provided
505 that the function returns \true.
506
507 Notice that if you want to to use the command line processing provided by
508 wxWidgets you have to call the base class version in the derived class
509 OnInit().
510
511 Return \true to continue processing, \false to exit the application
512 immediately.
513
514
515 \membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline}
516
517 \func{void}{OnInitCmdLine}{\param{wxCmdLineParser\& }{parser}}
518
519 Called from \helpref{OnInit}{wxapponinit} and may be used to initialize the
520 parser with the command line options for this application. The base class
521 versions adds support for a few standard options only.
522
523 \membersection{wxApp::OnRun}\label{wxapponrun}
524
525 \func{virtual int}{OnRun}{\void}
526
527 This virtual function is where the execution of a program written in wxWidgets
528 starts. The default implementation just enters the main loop and starts
529 handling the events until it terminates, either because
530 \helpref{ExitMainLoop}{wxappexitmainloop} has been explicitly called or because
531 the last frame has been deleted and
532 \helpref{GetExitOnFrameDelete}{wxappgetexitonframedelete} flag is \true (this
533 is the default).
534
535 The return value of this function becomes the exit code of the program, so it
536 should return $0$ in case of successful termination.
537
538
539 \membersection{wxApp::OnUnhandledException}\label{wxapponunhandledexception}
540
541 \func{virtual void}{OnUnhandledException}{\void}
542
543 This function is called when an unhandled C++ exception occurs inside
544 \helpref{OnRun()}{wxapponrun} (the exceptions which occur during the program
545 startup and shutdown might not be caught at all). Notice that by now the main
546 event loop has been terminated and the program will exit, if you want to
547 prevent this from happening (i.e. continue running after catching an exception)
548 you need to override \helpref{OnExceptionInMainLoop}{wxapponexceptioninmainloop}.
549
550 The default implementation shows information about the exception in debug build
551 but does nothing in the release build.
552
553
554 \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage}
555
556 \func{bool}{ProcessMessage}{\param{WXMSG *}{msg}}
557
558 Windows-only function for processing a message. This function
559 is called from the main message loop, checking for windows that
560 may wish to process it. The function returns true if the message
561 was processed, false otherwise. If you use wxWidgets with another class
562 library with its own message loop, you should make sure that this
563 function is called to allow wxWidgets to receive messages. For example,
564 to allow co-existence with the Microsoft Foundation Classes, override
565 the PreTranslateMessage function:
566
567 \begin{verbatim}
568 // Provide wxWidgets message loop compatibility
569 BOOL CTheApp::PreTranslateMessage(MSG *msg)
570 {
571 if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
572 return true;
573 else
574 return CWinApp::PreTranslateMessage(msg);
575 }
576 \end{verbatim}
577
578
579 \membersection{wxApp::Pending}\label{wxapppending}
580
581 \func{virtual bool}{Pending}{\void}
582
583 Returns true if unprocessed events are in the window system event queue.
584
585 \wxheading{See also}
586
587 \helpref{wxApp::Dispatch}{wxappdispatch}
588
589
590 \membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
591
592 \func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}, \param{wxIdleEvent\& }{event}}
593
594 Sends idle events to a window and its children.
595
596 Please note that this function is internal to wxWidgets and shouldn't be used
597 by user code.
598
599 \wxheading{Remarks}
600
601 These functions poll the top-level windows, and their children, for idle event processing.
602 If true is returned, more OnIdle processing is requested by one or more window.
603
604 \wxheading{See also}
605
606 \helpref{wxIdleEvent}{wxidleevent}
607
608
609 \membersection{wxApp::SetAppDisplayName}\label{wxappsetappdisplayname}
610
611 \func{void}{SetAppDisplayName}{\param{const wxString\& }{name}}
612
613 Set the application name to be used in the user-visible places such as window
614 titles. See \helpref{GetAppDisplayName}{wxappgetappdisplayname} for more about
615 the differences between the display name and name.
616
617
618 \membersection{wxApp::SetAppName}\label{wxappsetappname}
619
620 \func{void}{SetAppName}{\param{const wxString\& }{name}}
621
622 Sets the name of the application. This name should be used for file names,
623 configuration file entries and other internal strings. For the user-visible
624 strings, such as the window titles, the application display name set by
625 \helpref{SetAppDisplayName}{wxappsetappdisplayname} is used instead.
626
627 By default the application name is set to the name of its executable file.
628
629 \wxheading{See also}
630
631 \helpref{wxApp::GetAppName}{wxappgetappname}
632
633
634 \membersection{wxApp::SetClassName}\label{wxappsetclassname}
635
636 \func{void}{SetClassName}{\param{const wxString\& }{name}}
637
638 Sets the class name of the application. This may be used in a platform specific
639 manner to refer to the application.
640
641 \wxheading{See also}
642
643 \helpref{wxApp::GetClassName}{wxappgetclassname}
644
645
646 \membersection{wxApp::SetExitOnFrameDelete}\label{wxappsetexitonframedelete}
647
648 \func{void}{SetExitOnFrameDelete}{\param{bool}{ flag}}
649
650 Allows the programmer to specify whether the application will exit when the
651 top-level frame is deleted.
652
653 \wxheading{Parameters}
654
655 \docparam{flag}{If true (the default), the application will exit when the top-level frame is
656 deleted. If false, the application will continue to run.}
657
658 \wxheading{See also}
659
660 \helpref{wxApp::GetExitOnFrameDelete}{wxappgetexitonframedelete},\\
661 \helpref{wxApp shutdown overview}{wxappshutdownoverview}
662
663
664 \membersection{wxApp::SetInstance}\label{wxappsetinstance}
665
666 \func{static void}{SetInstance}{\param{wxAppConsole* }{app}}
667
668 Allows external code to modify global \texttt{wxTheApp}, but you should really
669 know what you're doing if you call it.
670
671 \wxheading{Parameters}
672
673 \docparam{app}{Replacement for the global application object.}
674
675 \wxheading{See also}
676
677 \helpref{wxApp::GetInstance}{wxappgetinstance}
678
679
680 \membersection{wxApp::SetTopWindow}\label{wxappsettopwindow}
681
682 \func{void}{SetTopWindow}{\param{wxWindow* }{window}}
683
684 Sets the `top' window. You can call this from within \helpref{wxApp::OnInit}{wxapponinit} to
685 let wxWidgets know which is the main window. You don't have to set the top window;
686 it is only a convenience so that (for example) certain dialogs without parents can use a
687 specific window as the top window. If no top window is specified by the application,
688 wxWidgets just uses the first frame or dialog in its top-level window list, when it
689 needs to use the top window.
690
691 \wxheading{Parameters}
692
693 \docparam{window}{The new top window.}
694
695 \wxheading{See also}
696
697 \helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit}
698
699
700
701 \membersection{wxApp::SetVendorName}\label{wxappsetvendorname}
702
703 \func{void}{SetVendorName}{\param{const wxString\& }{name}}
704
705 Sets the name of application's vendor. The name will be used
706 in registry access. A default name is set by
707 wxWidgets.
708
709 \wxheading{See also}
710
711 \helpref{wxApp::GetVendorName}{wxappgetvendorname}
712
713
714 \membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual}
715
716 \func{void}{SetUseBestVisual}{\param{bool}{ flag}, \param{bool}{ forceTrueColour = false}}
717
718 Allows the programmer to specify whether the application will use the best visual
719 on systems that support several visual on the same display. This is typically the
720 case under Solaris and IRIX, where the default visual is only 8-bit whereas certain
721 applications are supposed to run in TrueColour mode.
722
723 If \arg{forceTrueColour} is true then the application will try to force
724 using a TrueColour visual and abort the app if none is found.
725
726 Note that this function has to be called in the constructor of the {\tt wxApp}
727 instance and won't have any effect when called later on.
728
729 This function currently only has effect under GTK.
730
731 \wxheading{Parameters}
732
733 \docparam{flag}{If true, the app will use the best visual.}
734
735
736 \membersection{wxApp::HandleEvent}\label{wxapphandleevent}
737
738 \constfunc{virtual void}{HandleEvent}{\param{wxEvtHandler}{ *handler}, \param{wxEventFunction}{ func}, \param{wxEvent\& }{event}}
739
740 This function simply invokes the given method \arg{func} of the specified
741 event handler \arg{handler} with the \arg{event} as parameter. It exists solely
742 to allow to catch the C++ exceptions which could be thrown by all event
743 handlers in the application in one place: if you want to do this, override this
744 function in your wxApp-derived class and add try/catch clause(s) to it.
745
746
747 \membersection{wxApp::Yield}\label{wxappyield}
748
749 \func{bool}{Yield}{\param{bool}{ onlyIfNeeded = false}}
750
751 Yields control to pending messages in the windowing system. This can be useful, for example, when a
752 time-consuming process writes to a text window. Without an occasional
753 yield, the text window will not be updated properly, and on systems with
754 cooperative multitasking, such as Windows 3.1 other processes will not respond.
755
756 Caution should be exercised, however, since yielding may allow the
757 user to perform actions which are not compatible with the current task.
758 Disabling menu items or whole menus during processing can avoid unwanted
759 reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better
760 function.
761
762 Note that Yield() will not flush the message logs. This is intentional as
763 calling Yield() is usually done to quickly update the screen and popping up a
764 message box dialog may be undesirable. If you do wish to flush the log
765 messages immediately (otherwise it will be done during the next idle loop
766 iteration), call \helpref{wxLog::FlushActive}{wxlogflushactive}.
767
768 Calling Yield() recursively is normally an error and an assert failure is
769 raised in debug build if such situation is detected. However if the
770 {\it onlyIfNeeded} parameter is {\tt true}, the method will just silently
771 return {\tt false} instead.
772