]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
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 | ||
954b8ae6 JS |
25 | \wxheading{Include files} |
26 | ||
27 | <wx/app.h> | |
28 | ||
a660d684 KB |
29 | \wxheading{See also} |
30 | ||
31 | \helpref{wxApp overview}{wxappoverview} | |
32 | ||
33 | \latexignore{\rtfignore{\wxheading{Members}}} | |
34 | ||
35 | \membersection{wxApp::wxApp} | |
36 | ||
2fd284a4 | 37 | \func{void}{wxApp}{\void} |
a660d684 KB |
38 | |
39 | Constructor. Called implicitly with a definition of a wxApp object. | |
40 | ||
a660d684 KB |
41 | \membersection{wxApp::\destruct{wxApp}} |
42 | ||
43 | \func{void}{\destruct{wxApp}}{\void} | |
44 | ||
45 | Destructor. Will be called implicitly on program exit if the wxApp | |
46 | object is created on the stack. | |
47 | ||
48 | \membersection{wxApp::argc}\label{wxappargc} | |
49 | ||
50 | \member{int}{argc} | |
51 | ||
52 | Number of command line arguments (after environment-specific processing). | |
53 | ||
54 | \membersection{wxApp::argv}\label{wxappargv} | |
55 | ||
56 | \member{char **}{argv} | |
57 | ||
58 | Command line arguments (after environment-specific processing). | |
59 | ||
60 | \membersection{wxApp::CreateLogTarget}\label{wxappcreatelogtarget} | |
61 | ||
62 | \func{virtual wxLog*}{CreateLogTarget}{\void} | |
63 | ||
64 | Creates a wxLog class for the application to use for logging errors. The default | |
65 | implementation returns a new wxLogGui class. | |
66 | ||
67 | \wxheading{See also} | |
68 | ||
69 | \helpref{wxLog}{wxlog} | |
70 | ||
71 | \membersection{wxApp::Dispatch}\label{wxappdispatch} | |
72 | ||
73 | \func{void}{Dispatch}{\void} | |
74 | ||
75 | Dispatches the next event in the windowing system event queue. | |
76 | ||
77 | This can be used for programming event loops, e.g. | |
78 | ||
79 | \begin{verbatim} | |
80 | while (app.Pending()) | |
81 | Dispatch(); | |
82 | \end{verbatim} | |
83 | ||
84 | \wxheading{See also} | |
85 | ||
86 | \helpref{wxApp::Pending}{wxapppending} | |
87 | ||
88 | \membersection{wxApp::GetAppName}\label{wxappgetappname} | |
89 | ||
90 | \constfunc{wxString}{GetAppName}{\void} | |
91 | ||
92 | Returns the application name. | |
93 | ||
94 | \wxheading{Remarks} | |
95 | ||
96 | wxWindows sets this to a reasonable default before | |
97 | calling \helpref{wxApp::OnInit}{wxapponinit}, but the application can reset it at will. | |
98 | ||
99 | \membersection{wxApp::GetAuto3D}\label{wxappgetauto3d} | |
100 | ||
101 | \constfunc{bool}{GetAuto3D}{\void} | |
102 | ||
103 | Returns TRUE if 3D control mode is on, FALSE otherwise. | |
104 | ||
105 | \wxheading{See also} | |
106 | ||
107 | \helpref{wxApp::SetAuto3D}{wxappsetauto3d} | |
108 | ||
109 | \membersection{wxApp::GetClassName}\label{wxappgetclassname} | |
110 | ||
111 | \constfunc{wxString}{GetClassName}{\void} | |
112 | ||
113 | Gets the class name of the application. The class name may be used in a platform specific | |
114 | manner to refer to the application. | |
115 | ||
116 | \wxheading{See also} | |
117 | ||
118 | \helpref{wxApp::SetClassName}{wxappsetclassname} | |
119 | ||
f59d80ca | 120 | \membersection{wxApp::GetExitOnFrameDelete}\label{wxappgetexitonframedelete} |
a660d684 | 121 | |
f59d80ca | 122 | \constfunc{bool}{GetExitFrameOnDelete}{\void} |
a660d684 KB |
123 | |
124 | Returns TRUE if the application will exit when the top-level window is deleted, FALSE | |
125 | otherwise. | |
126 | ||
127 | \wxheading{See also} | |
128 | ||
f59d80ca | 129 | \helpref{wxApp::SetExitOnFrameDelete}{wxappsetexitonframedelete} |
a660d684 | 130 | |
a660d684 KB |
131 | \membersection{wxApp::GetTopWindow}\label{wxappgettopwindow} |
132 | ||
83a5b533 | 133 | \constfunc{virtual wxWindow *}{GetTopWindow}{\void} |
a660d684 KB |
134 | |
135 | Returns a pointer to the top window. | |
136 | ||
2a47d3c1 JS |
137 | \wxheading{Remarks} |
138 | ||
139 | If the top window hasn't been set using \helpref{wxApp::SetTopWindow}{wxappsettopwindow}, this | |
140 | function will find the first top-level window (frame or dialog) and return that. | |
141 | ||
a660d684 KB |
142 | \wxheading{See also} |
143 | ||
8480b297 RR |
144 | \helpref{SetTopWindow}{wxappsettopwindow} |
145 | ||
146 | \membersection{wxApp::GetUseBestVisual}\label{wxappgetusebestvisual} | |
147 | ||
148 | \constfunc{bool}{GetUseBestVisual}{\void} | |
149 | ||
103aab26 | 150 | Returns TRUE if the application will use the best visual on systems that support |
8480b297 RR |
151 | different visuals, FALSE otherwise. |
152 | ||
153 | \wxheading{See also} | |
154 | ||
155 | \helpref{SetUseBestVisual}{wxappsetusebestvisual} | |
a660d684 | 156 | |
e06b9569 | 157 | \membersection{wxApp::GetVendorName}\label{wxappgetvendorname} |
2aa59ef4 VS |
158 | |
159 | \constfunc{wxString}{GetVendorName}{\void} | |
160 | ||
161 | Returns the application's vendor name. | |
162 | ||
a660d684 KB |
163 | \membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop} |
164 | ||
165 | \func{void}{ExitMainLoop}{\void} | |
166 | ||
167 | Call this to explicitly exit the main message (event) loop. | |
168 | You should normally exit the main loop (and the application) by deleting | |
169 | the top window. | |
170 | ||
171 | \membersection{wxApp::Initialized}\label{wxappinitialized} | |
172 | ||
173 | \func{bool}{Initialized}{\void} | |
174 | ||
175 | Returns TRUE if the application has been initialized (i.e. if\rtfsp | |
176 | \helpref{wxApp::OnInit}{wxapponinit} has returned successfully). This can be useful for error | |
177 | message routines to determine which method of output is best for the | |
178 | current state of the program (some windowing systems may not like | |
179 | dialogs to pop up before the main loop has been entered). | |
180 | ||
181 | \membersection{wxApp::MainLoop}\label{wxappmainloop} | |
182 | ||
183 | \func{int}{MainLoop}{\void} | |
184 | ||
185 | Called by wxWindows on creation of the application. Override this if you wish | |
186 | to provide your own (environment-dependent) main loop. | |
187 | ||
188 | \wxheading{Return value} | |
189 | ||
190 | Returns 0 under X, and the wParam of the WM\_QUIT message under Windows. | |
191 | ||
a5f1fd3e VZ |
192 | %% VZ: OnXXX() functions should *not* be documented |
193 | %% | |
194 | %%\membersection{wxApp::OnActivate}\label{wxapponactivate} | |
195 | %% | |
196 | %%\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}} | |
197 | %% | |
198 | %%Provide this member function to know whether the application is being | |
199 | %%activated or deactivated (Windows only). | |
200 | %% | |
201 | %%\wxheading{See also} | |
202 | %% | |
203 | %%\helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent} | |
204 | %% | |
205 | %%\membersection{wxApp::OnCharHook}\label{wxapponcharhook} | |
206 | %% | |
207 | %%\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} | |
208 | %% | |
209 | %%This event handler function is called (under Windows only) to allow the window to intercept keyboard events | |
210 | %%before they are processed by child windows. | |
211 | %% | |
212 | %%\wxheading{Parameters} | |
213 | %% | |
214 | %%\docparam{event}{The keypress event.} | |
215 | %% | |
216 | %%\wxheading{Remarks} | |
217 | %% | |
218 | %%Use the wxEVT\_CHAR\_HOOK macro in your event table. | |
219 | %% | |
220 | %%If you use this member, you can selectively consume keypress events by calling\rtfsp | |
221 | %%\helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in. | |
222 | %% | |
223 | %%\wxheading{See also} | |
224 | %% | |
225 | %%\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp | |
226 | %%\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook} | |
227 | ||
228 | \membersection{wxApp::OnAssert}\label{wxapponassert} | |
229 | ||
230 | \func{void}{OnAssert}{\param{const wxChar }{*file}, \param{int }{line}, \param{const wxChar }{*msg}} | |
231 | ||
232 | This function is called when an assert failure occurs, i.e. the condition | |
233 | specified in \helpref{wxASSERT}{wxassert} macro evaluated to {\tt FALSE}. | |
1156efc1 | 234 | It is only called in debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) as |
a5f1fd3e VZ |
235 | asserts are not left in the release code at all. |
236 | ||
237 | The base class version show the default assert failure dialog box proposing to | |
238 | the user to stop the program, continue or ignore all subsequent asserts. | |
a660d684 | 239 | |
a5f1fd3e | 240 | \wxheading{Parameters} |
a660d684 | 241 | |
a5f1fd3e | 242 | \docparam{file}{the name of the source file where the assert occured} |
a660d684 | 243 | |
a5f1fd3e | 244 | \docparam{line}{the line number in this file where the assert occured} |
a660d684 | 245 | |
a5f1fd3e VZ |
246 | \docparam{msg}{the message specified as argument to |
247 | \helpref{wxASSERT\_MSG}{wxassertmsg} or \helpref{wxFAIL\_MSG}{wxfailmsg}, will | |
248 | be {\tt NULL} if just \helpref{wxASSERT}{wxassert} or \helpref{wxFAIL}{wxfail} | |
249 | was used} | |
a660d684 KB |
250 | |
251 | \membersection{wxApp::OnExit}\label{wxapponexit} | |
252 | ||
253 | \func{int}{OnExit}{\void} | |
254 | ||
255 | Provide this member function for any processing which needs to be done as | |
256 | the application is about to exit. | |
257 | ||
bf188f1a | 258 | \membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror} |
a37a5a73 | 259 | |
bf188f1a | 260 | \func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}} |
a37a5a73 | 261 | |
bf188f1a VZ |
262 | Called when command line parsing fails (i.e. an incorrect command line option |
263 | was specified by the user). The default behaviour is to show the program usage | |
264 | text and abort the program. | |
a37a5a73 | 265 | |
bf188f1a VZ |
266 | Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return |
267 | {\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program. | |
a37a5a73 VZ |
268 | |
269 | \wxheading{See also} | |
270 | ||
bf188f1a | 271 | \helpref{OnInitCmdLine}{wxapponinitcmdline} |
a37a5a73 | 272 | |
bf188f1a | 273 | \membersection{wxApp::OnCmdLineHelp}\label{wxapponcmdlinehelp} |
a660d684 | 274 | |
bf188f1a | 275 | \func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}} |
a660d684 | 276 | |
bf188f1a VZ |
277 | Called when the help option ({\tt --help}) was specified on the command line. |
278 | The default behaviour is to show the program usage text and abort the program. | |
a660d684 | 279 | |
bf188f1a VZ |
280 | Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return |
281 | {\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program. | |
a660d684 KB |
282 | |
283 | \wxheading{See also} | |
284 | ||
bf188f1a | 285 | \helpref{OnInitCmdLine}{wxapponinitcmdline} |
a660d684 | 286 | |
bf188f1a | 287 | \membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed} |
387a3b02 | 288 | |
bf188f1a | 289 | \func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}} |
387a3b02 | 290 | |
bf188f1a VZ |
291 | Called after the command line had been successfully parsed. You may override |
292 | this method to test for the values of the various parameters which could be | |
293 | set from the command line. | |
387a3b02 | 294 | |
bf188f1a VZ |
295 | Don't forget to call the base class version unless you want to suppress |
296 | processing of the standard command line options. | |
387a3b02 | 297 | |
bf188f1a VZ |
298 | Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return |
299 | {\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program. | |
387a3b02 | 300 | |
bf188f1a VZ |
301 | \wxheading{See also} |
302 | ||
303 | \helpref{OnInitCmdLine}{wxapponinitcmdline} | |
304 | ||
305 | \membersection{wxApp::OnFatalException}\label{wxapponfatalexception} | |
306 | ||
307 | \func{void}{OnFatalException}{\void} | |
387a3b02 | 308 | |
bf188f1a VZ |
309 | This function may be called if something fatal happens: an unhandled |
310 | exception under Win32 or a a fatal signal under Unix, for example. However, | |
311 | this will not happen by default: you have to explicitly call | |
312 | \helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions} to enable this. | |
387a3b02 | 313 | |
bf188f1a VZ |
314 | Generally speaking, this function should only show a message to the user and |
315 | return. You may attempt to save unsaved data but this is not guaranteed to | |
316 | work and, in fact, probably won't. | |
387a3b02 JS |
317 | |
318 | \wxheading{See also} | |
319 | ||
bf188f1a VZ |
320 | \helpref{wxHandleFatalExcetions}{wxhandlefatalexceptions} |
321 | ||
322 | %% VZ: the wxApp event handler are private and should not be documented here! | |
323 | %% | |
324 | %%\membersection{wxApp::OnIdle}\label{wxapponidle} | |
325 | %% | |
326 | %%\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}} | |
327 | %% | |
328 | %%Override this member function for any processing which needs to be done | |
329 | %%when the application is idle. You should call wxApp::OnIdle from your own function, | |
330 | %%since this forwards OnIdle events to windows and also performs garbage collection for | |
331 | %%windows whose destruction has been delayed. | |
332 | %% | |
333 | %%wxWindows' strategy for OnIdle processing is as follows. After pending user interface events for an | |
334 | %%application have all been processed, wxWindows sends an OnIdle event to the application object. wxApp::OnIdle itself | |
335 | %%sends an OnIdle event to each application window, allowing windows to do idle processing such as updating | |
336 | %%their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by | |
337 | %%caling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWindows will send another OnIdle | |
338 | %%event to the application object. This will occur in a loop until either a user event is found to be | |
339 | %%pending, or OnIdle requests no more time. Then all pending user events are processed until the system | |
340 | %%goes idle again, when OnIdle is called, and so on. | |
341 | %% | |
342 | %%\wxheading{See also} | |
343 | %% | |
344 | %%\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp | |
345 | %%\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents} | |
346 | %% | |
347 | %%\membersection{wxApp::OnEndSession}\label{wxapponendsession} | |
348 | %% | |
349 | %%\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}} | |
350 | %% | |
351 | %%This is an event handler function called when the operating system or GUI session is | |
352 | %%about to close down. The application has a chance to silently save information, | |
353 | %%and can optionally close itself. | |
354 | %% | |
355 | %%Use the EVT\_END\_SESSION event table macro to handle query end session events. | |
356 | %% | |
357 | %%The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument | |
358 | %%(forcing the application to close itself silently). | |
359 | %% | |
360 | %%\wxheading{Remarks} | |
361 | %% | |
362 | %%Under X, OnEndSession is called in response to the `die' event. | |
363 | %% | |
364 | %%Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message. | |
365 | %% | |
366 | %%\wxheading{See also} | |
367 | %% | |
368 | %%\helpref{wxWindow::Close}{wxwindowclose},\rtfsp | |
369 | %%\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp | |
370 | %%\helpref{wxCloseEvent}{wxcloseevent},\rtfsp | |
371 | %%\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession} | |
387a3b02 | 372 | |
a660d684 KB |
373 | \membersection{wxApp::OnInit}\label{wxapponinit} |
374 | ||
375 | \func{bool}{OnInit}{\void} | |
376 | ||
377 | This must be provided by the application, and will usually create the | |
bf188f1a VZ |
378 | application's main window, optionally calling |
379 | \helpref{wxApp::SetTopWindow}{wxappsettopwindow}. | |
380 | ||
381 | Notice that if you want to to use the command line processing provided by | |
382 | wxWindows you have to call the base class version in the derived class | |
383 | OnInit(). | |
a660d684 KB |
384 | |
385 | Return TRUE to continue processing, FALSE to exit the application. | |
386 | ||
bf188f1a VZ |
387 | \membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline} |
388 | ||
389 | \func{void}{OnInitCmdLine}{\param{wxCmdLineParser\& }{parser}} | |
390 | ||
391 | Called from \helpref{OnInit}{wxapponinit} and may be used to initialize the | |
392 | parser with the command line options for this application. The base class | |
393 | versions adds support for a few standard options only. | |
394 | ||
387a3b02 | 395 | \membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession} |
a660d684 | 396 | |
387a3b02 | 397 | \func{void}{OnQueryEndSession}{\param{wxCloseEvent\& }{event}} |
a660d684 | 398 | |
387a3b02 JS |
399 | This is an event handler function called when the operating system or GUI session is |
400 | about to close down. Typically, an application will try to save unsaved documents | |
401 | at this point. | |
402 | ||
403 | If \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns TRUE, the application | |
404 | is allowed to veto the shutdown by calling \helpref{wxCloseEvent::Veto}{wxcloseeventveto}. | |
405 | The application might veto the shutdown after prompting for documents to be saved, and the | |
406 | user has cancelled the save. | |
407 | ||
408 | Use the EVT\_QUERY\_END\_SESSION event table macro to handle query end session events. | |
409 | ||
410 | You should check whether the application is forcing the deletion of the window | |
411 | using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE, | |
412 | destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}. | |
413 | If not, it is up to you whether you respond by destroying the window. | |
414 | ||
415 | The default handler calls \helpref{wxWindow::Close}{wxwindowclose} on the top-level window, | |
416 | and vetoes the shutdown if Close returns FALSE. This will be sufficient for many applications. | |
417 | ||
418 | \wxheading{Remarks} | |
419 | ||
8771a323 | 420 | Under X, OnQueryEndSession is called in response to the `save session' event. |
387a3b02 JS |
421 | |
422 | Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message. | |
a660d684 KB |
423 | |
424 | \wxheading{See also} | |
425 | ||
387a3b02 JS |
426 | \helpref{wxWindow::Close}{wxwindowclose},\rtfsp |
427 | \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp | |
4d5a0f67 GD |
428 | \helpref{wxCloseEvent}{wxcloseevent} |
429 | %% GD: OnXXX functions are not documented | |
430 | %%\helpref{wxApp::OnEndSession}{wxapponendsession} | |
387a3b02 | 431 | |
a660d684 KB |
432 | \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage} |
433 | ||
434 | \func{bool}{ProcessMessage}{\param{MSG *}{msg}} | |
435 | ||
436 | Windows-only function for processing a message. This function | |
437 | is called from the main message loop, checking for windows that | |
438 | may wish to process it. The function returns TRUE if the message | |
439 | was processed, FALSE otherwise. If you use wxWindows with another class | |
440 | library with its own message loop, you should make sure that this | |
441 | function is called to allow wxWindows to receive messages. For example, | |
442 | to allow co-existance with the Microsoft Foundation Classes, override | |
443 | the PreTranslateMessage function: | |
444 | ||
445 | \begin{verbatim} | |
446 | // Provide wxWindows message loop compatibility | |
447 | BOOL CTheApp::PreTranslateMessage(MSG *msg) | |
448 | { | |
449 | if (wxTheApp && wxTheApp->ProcessMessage(msg)) | |
450 | return TRUE; | |
451 | else | |
452 | return CWinApp::PreTranslateMessage(msg); | |
453 | } | |
454 | \end{verbatim} | |
455 | ||
387a3b02 JS |
456 | \membersection{wxApp::Pending}\label{wxapppending} |
457 | ||
458 | \func{bool}{Pending}{\void} | |
459 | ||
f59d80ca | 460 | Returns TRUE if unprocessed events are in the window system event queue. |
387a3b02 JS |
461 | |
462 | \wxheading{See also} | |
463 | ||
464 | \helpref{wxApp::Dispatch}{wxappdispatch} | |
465 | ||
a660d684 KB |
466 | \membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents} |
467 | ||
468 | \func{bool}{SendIdleEvents}{\void} | |
469 | ||
470 | Sends idle events to all top-level windows. | |
471 | ||
472 | \func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}} | |
473 | ||
474 | Sends idle events to a window and its children. | |
475 | ||
476 | \wxheading{Remarks} | |
477 | ||
478 | These functions poll the top-level windows, and their children, for idle event processing. | |
479 | If TRUE is returned, more OnIdle processing is requested by one or more window. | |
480 | ||
481 | \wxheading{See also} | |
482 | ||
4d5a0f67 GD |
483 | %% GD: OnXXX functions are not documented |
484 | %%\helpref{wxApp::OnIdle}{wxapponidle} | |
485 | \helpref{wxWindow::OnIdle}{wxwindowonidle},\rtfsp | |
486 | \helpref{wxIdleEvent}{wxidleevent} | |
a660d684 KB |
487 | |
488 | \membersection{wxApp::SetAppName}\label{wxappsetappname} | |
489 | ||
490 | \func{void}{SetAppName}{\param{const wxString\& }{name}} | |
491 | ||
492 | Sets the name of the application. The name may be used in dialogs | |
493 | (for example by the document/view framework). A default name is set by | |
494 | wxWindows. | |
495 | ||
496 | \wxheading{See also} | |
497 | ||
498 | \helpref{wxApp::GetAppName}{wxappgetappname} | |
499 | ||
500 | \membersection{wxApp::SetAuto3D}\label{wxappsetauto3d} | |
501 | ||
502 | \func{void}{SetAuto3D}{\param{const bool}{ auto3D}} | |
503 | ||
504 | Switches automatic 3D controls on or off. | |
505 | ||
506 | \wxheading{Parameters} | |
507 | ||
508 | \docparam{auto3D}{If TRUE, all controls will be created with 3D appearances unless | |
509 | overridden for a control or dialog. The default is TRUE} | |
510 | ||
511 | \wxheading{Remarks} | |
512 | ||
513 | This has an effect on Windows only. | |
514 | ||
515 | \wxheading{See also} | |
516 | ||
517 | \helpref{wxApp::GetAuto3D}{wxappgetauto3d} | |
518 | ||
519 | \membersection{wxApp::SetClassName}\label{wxappsetclassname} | |
520 | ||
521 | \func{void}{SetClassName}{\param{const wxString\& }{name}} | |
522 | ||
523 | Sets the class name of the application. This may be used in a platform specific | |
524 | manner to refer to the application. | |
525 | ||
526 | \wxheading{See also} | |
527 | ||
528 | \helpref{wxApp::GetClassName}{wxappgetclassname} | |
529 | ||
f59d80ca | 530 | \membersection{wxApp::SetExitOnFrameDelete}\label{wxappsetexitonframedelete} |
a660d684 | 531 | |
f59d80ca | 532 | \func{void}{SetExitOnFrameDelete}{\param{bool}{ flag}} |
a660d684 KB |
533 | |
534 | Allows the programmer to specify whether the application will exit when the | |
535 | top-level frame is deleted. | |
536 | ||
537 | \wxheading{Parameters} | |
538 | ||
539 | \docparam{flag}{If TRUE (the default), the application will exit when the top-level frame is | |
540 | deleted. If FALSE, the application will continue to run.} | |
541 | ||
a660d684 KB |
542 | \membersection{wxApp::SetTopWindow}\label{wxappsettopwindow} |
543 | ||
544 | \func{void}{SetTopWindow}{\param{wxWindow* }{window}} | |
545 | ||
2a47d3c1 JS |
546 | Sets the `top' window. You can call this from within \helpref{wxApp::OnInit}{wxapponinit} to |
547 | let wxWindows know which is the main window. You don't have to set the top window; | |
f6bcfd97 | 548 | it is only a convenience so that (for example) certain dialogs without parents can use a |
2a47d3c1 JS |
549 | specific window as the top window. If no top window is specified by the application, |
550 | wxWindows just uses the first frame or dialog in its top-level window list, when it | |
551 | needs to use the top window. | |
a660d684 KB |
552 | |
553 | \wxheading{Parameters} | |
554 | ||
555 | \docparam{window}{The new top window.} | |
556 | ||
557 | \wxheading{See also} | |
558 | ||
559 | \helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit} | |
560 | ||
2aa59ef4 VS |
561 | |
562 | \membersection{wxApp::SetVendorName}\label{wxappsetvendorname} | |
563 | ||
564 | \func{void}{SetVendorName}{\param{const wxString\& }{name}} | |
565 | ||
566 | Sets the name of application's vendor. The name will be used | |
567 | in registry access. A default name is set by | |
568 | wxWindows. | |
569 | ||
570 | \wxheading{See also} | |
571 | ||
572 | \helpref{wxApp::GetVendorName}{wxappgetvendorname} | |
573 | ||
8480b297 RR |
574 | \membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual} |
575 | ||
576 | \func{void}{SetUseBestVisual}{\param{bool}{ flag}} | |
577 | ||
578 | Allows the programmer to specify whether the application will use the best visual | |
103aab26 RR |
579 | on systems that support several visual on the same display. This is typically the |
580 | case under Solaris and IRIX, where the default visual is only 8-bit whereas certain | |
581 | appications are supposed to run in TrueColour mode. | |
8480b297 | 582 | |
fa482912 | 583 | Note that this function has to be called in the constructor of the {\tt wxApp} |
8480b297 RR |
584 | instance and won't have any effect when called later on. |
585 | ||
586 | This function currently only has effect under GTK. | |
587 | ||
588 | \wxheading{Parameters} | |
589 | ||
590 | \docparam{flag}{If TRUE, the app will use the best visual.} | |
e06b9569 | 591 | |
5638d705 | 592 | \membersection{wxApp::Yield}\label{wxappyield} |
8461e4c2 VZ |
593 | |
594 | \func{bool}{Yield}{\param{bool}{ onlyIfNeeded = FALSE}} | |
595 | ||
596 | Yields control to pending messages in the windowing system. This can be useful, for example, when a | |
597 | time-consuming process writes to a text window. Without an occasional | |
598 | yield, the text window will not be updated properly, and on systems with | |
599 | cooperative multitasking, such as Windows 3.1 other processes will not respond. | |
600 | ||
601 | Caution should be exercised, however, since yielding may allow the | |
602 | user to perform actions which are not compatible with the current task. | |
603 | Disabling menu items or whole menus during processing can avoid unwanted | |
604 | reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better | |
605 | function. | |
606 | ||
607 | Note that Yield() will not flush the message logs. This is intentional as | |
608 | calling Yield() is usually done to quickly update the screen and popping up a | |
609 | message box dialog may be undesirable. If you do wish to flush the log | |
610 | messages immediately (otherwise it will be done during the next idle loop | |
611 | iteration), call \helpref{wxLog::FlushActive}{wxlogflushactive}. | |
612 | ||
613 | Calling Yield() recursively is normally an error and an assert failure is | |
614 | raised in debug build if such situation is detected. However if the the | |
615 | {\it onlyIfNeeded} parameter is {\tt TRUE}, the method will just silently | |
616 | return {\tt FALSE} instead. | |
617 |