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