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