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{See also}
  26
  27 \helpref{wxApp overview}{wxappoverview}
  28
  29 \latexignore{\rtfignore{\wxheading{Members}}}
  30
  31 \membersection{wxApp::wxApp}
  32
  33 \func{void}{wxApp}{\param{int}{ language = wxLANGUAGE\_ENGLISH}}
  34
  35 Constructor. Called implicitly with a definition of a wxApp object.
  36
  37 The argument is a language identifier; this is an experimental
  38 feature and will be expanded and documented in future versions.
  39
  40 TODO: completely rewrite the language stuff.
  41
  42 \membersection{wxApp::\destruct{wxApp}}
  43
  44 \func{void}{\destruct{wxApp}}{\void}
  45
  46 Destructor. Will be called implicitly on program exit if the wxApp
  47 object is created on the stack.
  48
  49 \membersection{wxApp::argc}\label{wxappargc}
  50
  51 \member{int}{argc}
  52
  53 Number of command line arguments (after environment-specific processing).
  54
  55 \membersection{wxApp::argv}\label{wxappargv}
  56
  57 \member{char **}{argv}
  58
  59 Command line arguments (after environment-specific processing).
  60
  61 \membersection{wxApp::CreateLogTarget}\label{wxappcreatelogtarget}
  62
  63 \func{virtual wxLog*}{CreateLogTarget}{\void}
  64
  65 Creates a wxLog class for the application to use for logging errors. The default
  66 implementation returns a new wxLogGui class.
  67
  68 \wxheading{See also}
  69
  70 \helpref{wxLog}{wxlog}
  71
  72 \membersection{wxApp::Dispatch}\label{wxappdispatch}
  73
  74 \func{void}{Dispatch}{\void}
  75
  76 Dispatches the next event in the windowing system event queue.
  77
  78 This can be used for programming event loops, e.g.
  79
  80 \begin{verbatim}
  81   while (app.Pending())
  82     Dispatch();
  83 \end{verbatim}
  84
  85 \wxheading{See also}
  86
  87 \helpref{wxApp::Pending}{wxapppending}
  88
  89 \membersection{wxApp::GetAppName}\label{wxappgetappname}
  90
  91 \constfunc{wxString}{GetAppName}{\void}
  92
  93 Returns the application name.
  94
  95 \wxheading{Remarks}
  96
  97 wxWindows sets this to a reasonable default before
  98 calling \helpref{wxApp::OnInit}{wxapponinit}, but the application can reset it at will.
  99
 100 \membersection{wxApp::GetAuto3D}\label{wxappgetauto3d}
 101
 102 \constfunc{bool}{GetAuto3D}{\void}
 103
 104 Returns TRUE if 3D control mode is on, FALSE otherwise.
 105
 106 \wxheading{See also}
 107
 108 \helpref{wxApp::SetAuto3D}{wxappsetauto3d}
 109
 110 \membersection{wxApp::GetClassName}\label{wxappgetclassname}
 111
 112 \constfunc{wxString}{GetClassName}{\void}
 113
 114 Gets the class name of the application. The class name may be used in a platform specific
 115 manner to refer to the application.
 116
 117 \wxheading{See also}
 118
 119 \helpref{wxApp::SetClassName}{wxappsetclassname}
 120
 121 \membersection{wxApp::GetExitOnDelete}\label{wxappgetexitondelete}
 122
 123 \constfunc{bool}{GetExitOnDelete}{\void}
 124
 125 Returns TRUE if the application will exit when the top-level window is deleted, FALSE
 126 otherwise.
 127
 128 \wxheading{See also}
 129
 130 \helpref{wxApp::SetExitOnDelete}{wxappsetexitondelete}
 131
 132 \membersection{wxApp::GetPrintMode}\label{wxappgetprintmode}
 133
 134 \constfunc{bool}{GetPrintMode}{\void}
 135
 136 Returns the print mode: see \helpref{wxApp::SetPrintMode}{wxappsetprintmode}.
 137
 138 \membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}
 139
 140 \constfunc{wxWindow *}{GetTopWindow}{\void}
 141
 142 Returns a pointer to the top window.
 143
 144 \wxheading{See also}
 145
 146 \helpref{wxApp::SetTopWindow}{wxappsettopwindow}
 147
 148 \membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
 149
 150 \func{void}{ExitMainLoop}{\void}
 151
 152 Call this to explicitly exit the main message (event) loop.
 153 You should normally exit the main loop (and the application) by deleting
 154 the top window.
 155
 156 \membersection{wxApp::Initialized}\label{wxappinitialized}
 157
 158 \func{bool}{Initialized}{\void}
 159
 160 Returns TRUE if the application has been initialized (i.e. if\rtfsp
 161 \helpref{wxApp::OnInit}{wxapponinit} has returned successfully).  This can be useful for error
 162 message routines to determine which method of output is best for the
 163 current state of the program (some windowing systems may not like
 164 dialogs to pop up before the main loop has been entered).
 165
 166 \membersection{wxApp::MainLoop}\label{wxappmainloop}
 167
 168 \func{int}{MainLoop}{\void}
 169
 170 Called by wxWindows on creation of the application. Override this if you wish
 171 to provide your own (environment-dependent) main loop.
 172
 173 \wxheading{Return value}
 174
 175 Returns 0 under X, and the wParam of the WM\_QUIT message under Windows.
 176
 177 \membersection{wxApp::OnActivate}\label{wxapponactivate}
 178
 179 \func{void}{OnActivate}{\param{wxActivateEvent\& }{event}}
 180
 181 Provide this member function to know whether the application is being
 182 activated or deactivated (Windows only).
 183
 184 \wxheading{See also}
 185
 186 \helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent}
 187
 188 \membersection{wxApp::OnExit}\label{wxapponexit}
 189
 190 \func{int}{OnExit}{\void}
 191
 192 Provide this member function for any processing which needs to be done as
 193 the application is about to exit.
 194
 195 \membersection{wxApp::OnCharHook}\label{wxapponcharhook}
 196
 197 \func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
 198
 199 This event handler function is called (under Windows only) to allow the window to intercept keyboard events
 200 before they are processed by child windows.
 201
 202 \wxheading{Parameters}
 203
 204 \docparam{event}{The keypress event.}
 205
 206 \wxheading{Remarks}
 207
 208 Use the wxEVT\_CHAR\_HOOK macro in your event table.
 209
 210 If you use this member, you can selectively consume keypress events by calling\rtfsp
 211 \helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in.
 212
 213 \wxheading{See also}
 214
 215 \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
 216 \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
 217
 218 \membersection{wxApp::OnIdle}\label{wxapponidle}
 219
 220 \func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
 221
 222 Override this member function for any processing which needs to be done
 223 when the application is idle. You should call wxApp::OnIdle from your own function,
 224 since this forwards OnIdle events to windows and also performs garbage collection for
 225 windows whose destruction has been delayed.
 226
 227 wxWindows' strategy for OnIdle processing is as follows. After pending user interface events for an
 228 application have all been processed, wxWindows sends an OnIdle event to the application object. wxApp::OnIdle itself
 229 sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
 230 their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
 231 caling \helpref{wxIdleEvent::ReqestMore}{wxidleeventrequestmore}, wxWindows will send another OnIdle
 232 event to the application event. This will occur in a loop until either a user event is found to be
 233 pending, or OnIdle requests no more time. Then all pending user events are processed until the system
 234 goes idle again, when OnIdle is called, and so on.
 235
 236 \wxheading{See also}
 237
 238 \helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
 239 \helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
 240
 241 \membersection{wxApp::OnInit}\label{wxapponinit}
 242
 243 \func{bool}{OnInit}{\void}
 244
 245 This must be provided by the application, and will usually create the
 246 application's main window, calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
 247
 248 Return TRUE to continue processing, FALSE to exit the application.
 249
 250 \membersection{wxApp::Pending}\label{wxapppending}
 251
 252 \func{bool}{Pending}{\void}
 253
 254 Returns TRUE if unprocessed events are in the window system event queue
 255 (MS Windows and Motif).
 256
 257 \wxheading{See also}
 258
 259 \helpref{wxApp::Dispatch}{wxappdispatch}
 260
 261 \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage}
 262
 263 \func{bool}{ProcessMessage}{\param{MSG *}{msg}}
 264
 265 Windows-only function for processing a message. This function
 266 is called from the main message loop, checking for windows that
 267 may wish to process it. The function returns TRUE if the message
 268 was processed, FALSE otherwise. If you use wxWindows with another class
 269 library with its own message loop, you should make sure that this
 270 function is called to allow wxWindows to receive messages. For example,
 271 to allow co-existance with the Microsoft Foundation Classes, override
 272 the PreTranslateMessage function:
 273
 274 \begin{verbatim}
 275 // Provide wxWindows message loop compatibility
 276 BOOL CTheApp::PreTranslateMessage(MSG *msg)
 277 {
 278   if (wxTheApp && wxTheApp->ProcessMessage(msg))
 279     return TRUE;
 280   else
 281     return CWinApp::PreTranslateMessage(msg);
 282 }
 283 \end{verbatim}
 284
 285 \membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
 286
 287 \func{bool}{SendIdleEvents}{\void}
 288
 289 Sends idle events to all top-level windows.
 290
 291 \func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}}
 292
 293 Sends idle events to a window and its children.
 294
 295 \wxheading{Remarks}
 296
 297 These functions poll the top-level windows, and their children, for idle event processing.
 298 If TRUE is returned, more OnIdle processing is requested by one or more window.
 299
 300 \wxheading{See also}
 301
 302 \helpref{wxApp::OnIdle}{wxapponidle}, \helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent}
 303
 304 \membersection{wxApp::SetAppName}\label{wxappsetappname}
 305
 306 \func{void}{SetAppName}{\param{const wxString\& }{name}}
 307
 308 Sets the name of the application. The name may be used in dialogs
 309 (for example by the document/view framework). A default name is set by
 310 wxWindows.
 311
 312 \wxheading{See also}
 313
 314 \helpref{wxApp::GetAppName}{wxappgetappname}
 315
 316 \membersection{wxApp::SetAuto3D}\label{wxappsetauto3d}
 317
 318 \func{void}{SetAuto3D}{\param{const bool}{ auto3D}}
 319
 320 Switches automatic 3D controls on or off.
 321
 322 \wxheading{Parameters}
 323
 324 \docparam{auto3D}{If TRUE, all controls will be created with 3D appearances unless
 325 overridden for a control or dialog. The default is TRUE}
 326
 327 \wxheading{Remarks}
 328
 329 This has an effect on Windows only.
 330
 331 \wxheading{See also}
 332
 333 \helpref{wxApp::GetAuto3D}{wxappgetauto3d}
 334
 335 \membersection{wxApp::SetClassName}\label{wxappsetclassname}
 336
 337 \func{void}{SetClassName}{\param{const wxString\& }{name}}
 338
 339 Sets the class name of the application. This may be used in a platform specific
 340 manner to refer to the application.
 341
 342 \wxheading{See also}
 343
 344 \helpref{wxApp::GetClassName}{wxappgetclassname}
 345
 346 \membersection{wxApp::SetExitOnDelete}\label{wxappsetexitondelete}
 347
 348 \func{void}{SetExitOnDelete}{\param{bool}{ flag}}
 349
 350 Allows the programmer to specify whether the application will exit when the
 351 top-level frame is deleted.
 352
 353 \wxheading{Parameters}
 354
 355 \docparam{flag}{If TRUE (the default), the application will exit when the top-level frame is
 356 deleted. If FALSE, the application will continue to run.}
 357
 358 \wxheading{Remarks}
 359
 360 Currently, setting this to FALSE only has an effect under Windows.
 361
 362 \membersection{wxApp::SetPrintMode}\label{wxappsetprintmode}
 363
 364 \func{void}{SetPrintMode}{\param{int}{ mode}}
 365
 366 Sets the print mode determining what printing facilities will be
 367 used by the printing framework.
 368
 369 \wxheading{Parameters}
 370
 371 \docparam{mode}{This can be one of:
 372
 373 \begin{twocollist}\itemsep=0pt
 374 \twocolitem{{\bf wxPRINT\_WINDOWS}}{Under Windows, use Windows printing (wxPrinterDC). This is the
 375 default under Windows.}
 376 \twocolitem{{\bf wxPRINT\_POSTSCRIPT}}{Use PostScript printing (wxPostScriptDC). This is the
 377 default for non-Windows platforms.}
 378 \end{twocollist}
 379 }%
 380
 381 \membersection{wxApp::SetTopWindow}\label{wxappsettopwindow}
 382
 383 \func{void}{SetTopWindow}{\param{wxWindow* }{window}}
 384
 385 Sets the `top' window. You should normally call this from within \helpref{wxApp::OnInit}{wxapponinit} to
 386 let wxWindows know which is the main window.
 387
 388 \wxheading{Parameters}
 389
 390 \docparam{window}{The new top window.}
 391
 392 \wxheading{See also}
 393
 394 \helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit}
 395