]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/app.tex
v2.2.1 TAGGED copy ported over to main trunk of CVS
[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 wxWindows 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{See also}
30
31 \helpref{wxApp overview}{wxappoverview}
32
33 \latexignore{\rtfignore{\wxheading{Members}}}
34
35 \membersection{wxApp::wxApp}
36
37 \func{void}{wxApp}{\void}
38
39 Constructor. Called implicitly with a definition of a wxApp object.
40
41 % VZ: there is no such feature so far...
42 % The argument is a language identifier; this is an experimental
43 % feature and will be expanded and documented in future versions.
44
45 \membersection{wxApp::\destruct{wxApp}}
46
47 \func{void}{\destruct{wxApp}}{\void}
48
49 Destructor. Will be called implicitly on program exit if the wxApp
50 object is created on the stack.
51
52 \membersection{wxApp::argc}\label{wxappargc}
53
54 \member{int}{argc}
55
56 Number of command line arguments (after environment-specific processing).
57
58 \membersection{wxApp::argv}\label{wxappargv}
59
60 \member{char **}{argv}
61
62 Command line arguments (after environment-specific processing).
63
64 \membersection{wxApp::CreateLogTarget}\label{wxappcreatelogtarget}
65
66 \func{virtual wxLog*}{CreateLogTarget}{\void}
67
68 Creates a wxLog class for the application to use for logging errors. The default
69 implementation returns a new wxLogGui class.
70
71 \wxheading{See also}
72
73 \helpref{wxLog}{wxlog}
74
75 \membersection{wxApp::Dispatch}\label{wxappdispatch}
76
77 \func{void}{Dispatch}{\void}
78
79 Dispatches the next event in the windowing system event queue.
80
81 This can be used for programming event loops, e.g.
82
83 \begin{verbatim}
84 while (app.Pending())
85 Dispatch();
86 \end{verbatim}
87
88 \wxheading{See also}
89
90 \helpref{wxApp::Pending}{wxapppending}
91
92 \membersection{wxApp::GetAppName}\label{wxappgetappname}
93
94 \constfunc{wxString}{GetAppName}{\void}
95
96 Returns the application name.
97
98 \wxheading{Remarks}
99
100 wxWindows sets this to a reasonable default before
101 calling \helpref{wxApp::OnInit}{wxapponinit}, but the application can reset it at will.
102
103 \membersection{wxApp::GetAuto3D}\label{wxappgetauto3d}
104
105 \constfunc{bool}{GetAuto3D}{\void}
106
107 Returns TRUE if 3D control mode is on, FALSE otherwise.
108
109 \wxheading{See also}
110
111 \helpref{wxApp::SetAuto3D}{wxappsetauto3d}
112
113 \membersection{wxApp::GetClassName}\label{wxappgetclassname}
114
115 \constfunc{wxString}{GetClassName}{\void}
116
117 Gets the class name of the application. The class name may be used in a platform specific
118 manner to refer to the application.
119
120 \wxheading{See also}
121
122 \helpref{wxApp::SetClassName}{wxappsetclassname}
123
124 \membersection{wxApp::GetExitOnFrameDelete}\label{wxappgetexitonframedelete}
125
126 \constfunc{bool}{GetExitFrameOnDelete}{\void}
127
128 Returns TRUE if the application will exit when the top-level window is deleted, FALSE
129 otherwise.
130
131 \wxheading{See also}
132
133 \helpref{wxApp::SetExitOnFrameDelete}{wxappsetexitonframedelete}
134
135 \membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}
136
137 \constfunc{wxWindow *}{GetTopWindow}{\void}
138
139 Returns a pointer to the top window.
140
141 \wxheading{Remarks}
142
143 If the top window hasn't been set using \helpref{wxApp::SetTopWindow}{wxappsettopwindow}, this
144 function will find the first top-level window (frame or dialog) and return that.
145
146 \wxheading{See also}
147
148 \helpref{SetTopWindow}{wxappsettopwindow}
149
150 \membersection{wxApp::GetUseBestVisual}\label{wxappgetusebestvisual}
151
152 \constfunc{bool}{GetUseBestVisual}{\void}
153
154 Returns TRUE if the application will use the best visual on systems that support
155 different visuals, FALSE otherwise.
156
157 \wxheading{See also}
158
159 \helpref{SetUseBestVisual}{wxappsetusebestvisual}
160
161 \membersection{wxApp::GetVendorName}\label{wxappgetvendorname}
162
163 \constfunc{wxString}{GetVendorName}{\void}
164
165 Returns the application's vendor name.
166
167 \membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
168
169 \func{void}{ExitMainLoop}{\void}
170
171 Call this to explicitly exit the main message (event) loop.
172 You should normally exit the main loop (and the application) by deleting
173 the top window.
174
175 \membersection{wxApp::Initialized}\label{wxappinitialized}
176
177 \func{bool}{Initialized}{\void}
178
179 Returns TRUE if the application has been initialized (i.e. if\rtfsp
180 \helpref{wxApp::OnInit}{wxapponinit} has returned successfully). This can be useful for error
181 message routines to determine which method of output is best for the
182 current state of the program (some windowing systems may not like
183 dialogs to pop up before the main loop has been entered).
184
185 \membersection{wxApp::MainLoop}\label{wxappmainloop}
186
187 \func{int}{MainLoop}{\void}
188
189 Called by wxWindows on creation of the application. Override this if you wish
190 to provide your own (environment-dependent) main loop.
191
192 \wxheading{Return value}
193
194 Returns 0 under X, and the wParam of the WM\_QUIT message under Windows.
195
196 \membersection{wxApp::OnActivate}\label{wxapponactivate}
197
198 \func{void}{OnActivate}{\param{wxActivateEvent\& }{event}}
199
200 Provide this member function to know whether the application is being
201 activated or deactivated (Windows only).
202
203 \wxheading{See also}
204
205 \helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent}
206
207 \membersection{wxApp::OnExit}\label{wxapponexit}
208
209 \func{int}{OnExit}{\void}
210
211 Provide this member function for any processing which needs to be done as
212 the application is about to exit.
213
214 \membersection{wxApp::OnCharHook}\label{wxapponcharhook}
215
216 \func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
217
218 This event handler function is called (under Windows only) to allow the window to intercept keyboard events
219 before they are processed by child windows.
220
221 \wxheading{Parameters}
222
223 \docparam{event}{The keypress event.}
224
225 \wxheading{Remarks}
226
227 Use the wxEVT\_CHAR\_HOOK macro in your event table.
228
229 If you use this member, you can selectively consume keypress events by calling\rtfsp
230 \helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in.
231
232 \wxheading{See also}
233
234 \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
235 \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
236
237 \membersection{wxApp::OnFatalException}\label{wxapponfatalexception}
238
239 \func{void}{OnFatalException}{\void}
240
241 This function may be called if something fatal happens: an unhandled
242 exception under Win32 or a a fatal signal under Unix, for example. However,
243 this will not happen by default: you have to explicitly call
244 \helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions} to enable this.
245
246 Generally speaking, this function should only show a message to the user and
247 return. You may attempt to save unsaved data but this is not guaranteed to
248 work and, in fact, probably won't.
249
250 \wxheading{See also}
251
252 \helpref{wxHandleFatalExcetions}{wxhandlefatalexceptions}
253
254 \membersection{wxApp::OnIdle}\label{wxapponidle}
255
256 \func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
257
258 Override this member function for any processing which needs to be done
259 when the application is idle. You should call wxApp::OnIdle from your own function,
260 since this forwards OnIdle events to windows and also performs garbage collection for
261 windows whose destruction has been delayed.
262
263 wxWindows' strategy for OnIdle processing is as follows. After pending user interface events for an
264 application have all been processed, wxWindows sends an OnIdle event to the application object. wxApp::OnIdle itself
265 sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
266 their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
267 caling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWindows will send another OnIdle
268 event to the application object. This will occur in a loop until either a user event is found to be
269 pending, or OnIdle requests no more time. Then all pending user events are processed until the system
270 goes idle again, when OnIdle is called, and so on.
271
272 \wxheading{See also}
273
274 \helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
275 \helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
276
277 \membersection{wxApp::OnEndSession}\label{wxapponendsession}
278
279 \func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}}
280
281 This is an event handler function called when the operating system or GUI session is
282 about to close down. The application has a chance to silently save information,
283 and can optionally close itself.
284
285 Use the EVT\_END\_SESSION event table macro to handle query end session events.
286
287 The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument
288 (forcing the application to close itself silently).
289
290 \wxheading{Remarks}
291
292 Under X, OnEndSession is called in response to the `die' event.
293
294 Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message.
295
296 \wxheading{See also}
297
298 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
299 \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
300 \helpref{wxCloseEvent}{wxcloseevent},\rtfsp
301 \helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession}
302
303 \membersection{wxApp::OnInit}\label{wxapponinit}
304
305 \func{bool}{OnInit}{\void}
306
307 This must be provided by the application, and will usually create the
308 application's main window, optionally calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
309
310 Return TRUE to continue processing, FALSE to exit the application.
311
312 \membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession}
313
314 \func{void}{OnQueryEndSession}{\param{wxCloseEvent\& }{event}}
315
316 This is an event handler function called when the operating system or GUI session is
317 about to close down. Typically, an application will try to save unsaved documents
318 at this point.
319
320 If \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns TRUE, the application
321 is allowed to veto the shutdown by calling \helpref{wxCloseEvent::Veto}{wxcloseeventveto}.
322 The application might veto the shutdown after prompting for documents to be saved, and the
323 user has cancelled the save.
324
325 Use the EVT\_QUERY\_END\_SESSION event table macro to handle query end session events.
326
327 You should check whether the application is forcing the deletion of the window
328 using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE,
329 destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
330 If not, it is up to you whether you respond by destroying the window.
331
332 The default handler calls \helpref{wxWindow::Close}{wxwindowclose} on the top-level window,
333 and vetoes the shutdown if Close returns FALSE. This will be sufficient for many applications.
334
335 \wxheading{Remarks}
336
337 Under X, OnQueryEndSession is called in response to the `save session' event.
338
339 Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message.
340
341 \wxheading{See also}
342
343 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
344 \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
345 \helpref{wxCloseEvent}{wxcloseevent},\rtfsp
346 \helpref{wxApp::OnEndSession}{wxapponendsession}
347
348 \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage}
349
350 \func{bool}{ProcessMessage}{\param{MSG *}{msg}}
351
352 Windows-only function for processing a message. This function
353 is called from the main message loop, checking for windows that
354 may wish to process it. The function returns TRUE if the message
355 was processed, FALSE otherwise. If you use wxWindows with another class
356 library with its own message loop, you should make sure that this
357 function is called to allow wxWindows to receive messages. For example,
358 to allow co-existance with the Microsoft Foundation Classes, override
359 the PreTranslateMessage function:
360
361 \begin{verbatim}
362 // Provide wxWindows message loop compatibility
363 BOOL CTheApp::PreTranslateMessage(MSG *msg)
364 {
365 if (wxTheApp && wxTheApp->ProcessMessage(msg))
366 return TRUE;
367 else
368 return CWinApp::PreTranslateMessage(msg);
369 }
370 \end{verbatim}
371
372 \membersection{wxApp::Pending}\label{wxapppending}
373
374 \func{bool}{Pending}{\void}
375
376 Returns TRUE if unprocessed events are in the window system event queue.
377
378 \wxheading{See also}
379
380 \helpref{wxApp::Dispatch}{wxappdispatch}
381
382 \membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
383
384 \func{bool}{SendIdleEvents}{\void}
385
386 Sends idle events to all top-level windows.
387
388 \func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}}
389
390 Sends idle events to a window and its children.
391
392 \wxheading{Remarks}
393
394 These functions poll the top-level windows, and their children, for idle event processing.
395 If TRUE is returned, more OnIdle processing is requested by one or more window.
396
397 \wxheading{See also}
398
399 \helpref{wxApp::OnIdle}{wxapponidle}, \helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent}
400
401 \membersection{wxApp::SetAppName}\label{wxappsetappname}
402
403 \func{void}{SetAppName}{\param{const wxString\& }{name}}
404
405 Sets the name of the application. The name may be used in dialogs
406 (for example by the document/view framework). A default name is set by
407 wxWindows.
408
409 \wxheading{See also}
410
411 \helpref{wxApp::GetAppName}{wxappgetappname}
412
413 \membersection{wxApp::SetAuto3D}\label{wxappsetauto3d}
414
415 \func{void}{SetAuto3D}{\param{const bool}{ auto3D}}
416
417 Switches automatic 3D controls on or off.
418
419 \wxheading{Parameters}
420
421 \docparam{auto3D}{If TRUE, all controls will be created with 3D appearances unless
422 overridden for a control or dialog. The default is TRUE}
423
424 \wxheading{Remarks}
425
426 This has an effect on Windows only.
427
428 \wxheading{See also}
429
430 \helpref{wxApp::GetAuto3D}{wxappgetauto3d}
431
432 \membersection{wxApp::SetClassName}\label{wxappsetclassname}
433
434 \func{void}{SetClassName}{\param{const wxString\& }{name}}
435
436 Sets the class name of the application. This may be used in a platform specific
437 manner to refer to the application.
438
439 \wxheading{See also}
440
441 \helpref{wxApp::GetClassName}{wxappgetclassname}
442
443 \membersection{wxApp::SetExitOnFrameDelete}\label{wxappsetexitonframedelete}
444
445 \func{void}{SetExitOnFrameDelete}{\param{bool}{ flag}}
446
447 Allows the programmer to specify whether the application will exit when the
448 top-level frame is deleted.
449
450 \wxheading{Parameters}
451
452 \docparam{flag}{If TRUE (the default), the application will exit when the top-level frame is
453 deleted. If FALSE, the application will continue to run.}
454
455 \membersection{wxApp::SetTopWindow}\label{wxappsettopwindow}
456
457 \func{void}{SetTopWindow}{\param{wxWindow* }{window}}
458
459 Sets the `top' window. You can call this from within \helpref{wxApp::OnInit}{wxapponinit} to
460 let wxWindows know which is the main window. You don't have to set the top window;
461 it is only a convenience so that (for example) certain dialogs without parents can use a
462 specific window as the top window. If no top window is specified by the application,
463 wxWindows just uses the first frame or dialog in its top-level window list, when it
464 needs to use the top window.
465
466 \wxheading{Parameters}
467
468 \docparam{window}{The new top window.}
469
470 \wxheading{See also}
471
472 \helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit}
473
474
475 \membersection{wxApp::SetVendorName}\label{wxappsetvendorname}
476
477 \func{void}{SetVendorName}{\param{const wxString\& }{name}}
478
479 Sets the name of application's vendor. The name will be used
480 in registry access. A default name is set by
481 wxWindows.
482
483 \wxheading{See also}
484
485 \helpref{wxApp::GetVendorName}{wxappgetvendorname}
486
487 \membersection{wxApp::GetStdIcon}\label{wxappgetstdicon}
488
489 \func{virtual wxIcon}{GetStdIcon}{\param{int }{which}} const
490
491 Returns the icons used by wxWindows internally, e.g. the ones used for
492 message boxes. This function is used internally and
493 can be overridden by the user to change the default icons.
494
495 \wxheading{Parameters}
496
497 \docparam{which}{One of the wxICON\_XXX specifies which icon to return.}
498
499 See \helpref{wxMessageBox}{wxmessagebox} for a list of icon identifiers.
500
501 \membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual}
502
503 \func{void}{SetUseBestVisual}{\param{bool}{ flag}}
504
505 Allows the programmer to specify whether the application will use the best visual
506 on systems that support several visual on the same display. This is typically the
507 case under Solaris and IRIX, where the default visual is only 8-bit whereas certain
508 appications are supposed to run in TrueColour mode.
509
510 Note that this function has to be called in the constructor of the {\tt wxApp}
511 instance and won't have any effect when called later on.
512
513 This function currently only has effect under GTK.
514
515 \wxheading{Parameters}
516
517 \docparam{flag}{If TRUE, the app will use the best visual.}
518