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