X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b82827dd43caa489eade15cc02edef7fb79e8c20..42d9ad7949254ed53f89ad6306dcb2a266bfffb3:/docs/latex/wx/app.tex

diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex
index 4581eabe5d..adefdadd83 100644
--- a/docs/latex/wx/app.tex
+++ b/docs/latex/wx/app.tex
@@ -12,7 +12,7 @@ objects in the application.
 \end{itemize}
 
 You should use the macro IMPLEMENT\_APP(appClass) in your application implementation
-file to tell wxWindows how to create an instance of your application class.
+file to tell wxWidgets how to create an instance of your application class.
 
 Use DECLARE\_APP(appClass) in a header file if you want the wxGetApp function (which returns
 a reference to your application object) to be visible to other files.
@@ -22,39 +22,55 @@ a reference to your application object) to be visible to other files.
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
+\wxheading{Include files}
+
+<wx/app.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
 \wxheading{See also}
 
 \helpref{wxApp overview}{wxappoverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxApp::wxApp}
 
-\func{void}{wxApp}{\void}
+\membersection{wxApp::wxApp}\label{wxappctor}
+
+\func{}{wxApp}{\void}
 
 Constructor. Called implicitly with a definition of a wxApp object.
 
-The argument is a language identifier; this is an experimental
-feature and will be expanded and documented in future versions.
 
-\membersection{wxApp::\destruct{wxApp}}
+\membersection{wxApp::\destruct{wxApp}}\label{wxappdtor}
 
-\func{void}{\destruct{wxApp}}{\void}
+\func{virtual}{\destruct{wxApp}}{\void}
 
 Destructor. Will be called implicitly on program exit if the wxApp
 object is created on the stack.
 
+
 \membersection{wxApp::argc}\label{wxappargc}
 
 \member{int}{argc}
 
 Number of command line arguments (after environment-specific processing).
 
+
 \membersection{wxApp::argv}\label{wxappargv}
 
-\member{char **}{argv}
+\member{wxChar **}{argv}
 
 Command line arguments (after environment-specific processing).
+Under Windows and Linux/Unix, you should parse the command line
+arguments and check for files to be opened when starting your
+application. Under OS X, you need to override \helpref{MacOpenFile}{wxappmacopenfile}
+since command line arguments are used differently there.
+
+You may use the \helpref{wxCmdLineParser}{wxcmdlineparser} to
+parse command line arguments.
 
 \membersection{wxApp::CreateLogTarget}\label{wxappcreatelogtarget}
 
@@ -67,9 +83,22 @@ implementation returns a new wxLogGui class.
 
 \helpref{wxLog}{wxlog}
 
+
+\membersection{wxApp::CreateTraits}\label{wxappcreatetraits}
+
+\func{virtual wxAppTraits *}{CreateTraits}{\void}
+
+Creates the \helpref{wxAppTraits}{wxapptraits} object when \helpref{GetTraits}{wxappgettraits}
+needs it for the first time.
+
+\wxheading{See also}
+
+\helpref{wxAppTraits}{wxapptraits}
+
+
 \membersection{wxApp::Dispatch}\label{wxappdispatch}
 
-\func{void}{Dispatch}{\void}
+\func{virtual void}{Dispatch}{\void}
 
 Dispatches the next event in the windowing system event queue.
 
@@ -84,6 +113,43 @@ This can be used for programming event loops, e.g.
 
 \helpref{wxApp::Pending}{wxapppending}
 
+
+\membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
+
+\func{virtual void}{ExitMainLoop}{\void}
+
+Call this to explicitly exit the main message (event) loop.
+You should normally exit the main loop (and the application) by deleting
+the top window.
+
+
+\membersection{wxApp::FilterEvent}\label{wxappfilterevent}
+
+\func{int}{FilterEvent}{\param{wxEvent\& }{event}}
+
+This function is called before processing any event and allows the application
+to preempt the processing of some events. If this method returns $-1$ the event
+is processed normally, otherwise either {\tt true} or {\tt false} should be
+returned and the event processing stops immediately considering that the event
+had been already processed (for the former return value) or that it is not
+going to be processed at all (for the latter one).
+
+
+\membersection{wxApp::GetAppDisplayName}\label{wxappgetappdisplayname}
+
+\constfunc{wxString}{GetAppDisplayName}{\void}
+
+Returns the user-readable application name. The difference between this string
+and the one returned by \helpref{GetAppName}{wxappgetappname} is that this one
+is meant to be shown to the user and so should be used for the window titles,
+page headers and so on while the other one should be only used internally, e.g.
+for the file names or configuration file keys.
+
+By default, returns the same string as \helpref{GetAppName}{wxappgetappname}.
+
+\newsince{2.9.0}
+
+
 \membersection{wxApp::GetAppName}\label{wxappgetappname}
 
 \constfunc{wxString}{GetAppName}{\void}
@@ -92,18 +158,13 @@ Returns the application name.
 
 \wxheading{Remarks}
 
-wxWindows sets this to a reasonable default before
+wxWidgets sets this to a reasonable default before
 calling \helpref{wxApp::OnInit}{wxapponinit}, but the application can reset it at will.
 
-\membersection{wxApp::GetAuto3D}\label{wxappgetauto3d}
-
-\constfunc{bool}{GetAuto3D}{\void}
-
-Returns TRUE if 3D control mode is on, FALSE otherwise.
-
 \wxheading{See also}
 
-\helpref{wxApp::SetAuto3D}{wxappsetauto3d}
+\helpref{GetAppDisplayName}{wxappgetappdisplayname}
+
 
 \membersection{wxApp::GetClassName}\label{wxappgetclassname}
 
@@ -116,281 +177,516 @@ manner to refer to the application.
 
 \helpref{wxApp::SetClassName}{wxappsetclassname}
 
-\membersection{wxApp::GetExitOnDelete}\label{wxappgetexitondelete}
 
-\constfunc{bool}{GetExitOnDelete}{\void}
+\membersection{wxApp::GetExitOnFrameDelete}\label{wxappgetexitonframedelete}
+
+\constfunc{bool}{GetExitOnFrameDelete}{\void}
 
-Returns TRUE if the application will exit when the top-level window is deleted, FALSE
+Returns true if the application will exit when the top-level window is deleted, false
 otherwise.
 
 \wxheading{See also}
 
-\helpref{wxApp::SetExitOnDelete}{wxappsetexitondelete}
+\helpref{wxApp::SetExitOnFrameDelete}{wxappsetexitonframedelete},\\
+\helpref{wxApp shutdown overview}{wxappshutdownoverview}
 
-\membersection{wxApp::GetPrintMode}\label{wxappgetprintmode}
 
-\constfunc{bool}{GetPrintMode}{\void}
+\membersection{wxApp::GetInstance}\label{wxappgetinstance}
+
+\func{static wxAppConsole *}{GetInstance}{\void}
+
+Returns the one and only global application object.
+Usually \texttt{wxTheApp} is usead instead.
+
+\wxheading{See also}
+
+\helpref{wxApp::SetInstance}{wxappsetinstance}
 
-Returns the print mode: see \helpref{wxApp::SetPrintMode}{wxappsetprintmode}.
 
 \membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}
 
-\constfunc{wxWindow *}{GetTopWindow}{\void}
+\constfunc{virtual wxWindow *}{GetTopWindow}{\void}
 
 Returns a pointer to the top window.
 
+\wxheading{Remarks}
+
+If the top window hasn't been set using \helpref{wxApp::SetTopWindow}{wxappsettopwindow}, this
+function will find the first top-level window (frame or dialog) and return that.
+
 \wxheading{See also}
 
-\helpref{wxApp::SetTopWindow}{wxappsettopwindow}
+\helpref{SetTopWindow}{wxappsettopwindow}
 
-\membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
 
-\func{void}{ExitMainLoop}{\void}
 
-Call this to explicitly exit the main message (event) loop.
-You should normally exit the main loop (and the application) by deleting
-the top window.
+\membersection{wxApp::GetTraits}\label{wxappgettraits}
+
+\func{wxAppTraits *}{GetTraits}{\void}
+
+Returns a pointer to the \helpref{wxAppTraits}{wxapptraits} object for the application.
+If you want to customize the \helpref{wxAppTraits}{wxapptraits} object, you must override the
+\helpref{CreateTraits}{wxappcreatetraits} function.
+
+
+
+\membersection{wxApp::GetUseBestVisual}\label{wxappgetusebestvisual}
+
+\constfunc{bool}{GetUseBestVisual}{\void}
+
+Returns true if the application will use the best visual on systems that support
+different visuals, false otherwise.
+
+\wxheading{See also}
+
+\helpref{SetUseBestVisual}{wxappsetusebestvisual}
+
+
+\membersection{wxApp::GetVendorDisplayName}\label{wxappgetvendordisplayname}
+
+\constfunc{wxString}{GetVendorDisplayName}{\void}
+
+Returns the user-readable vendor name. The difference between this string
+and the one returned by \helpref{GetVendorName}{wxappgetvendorname} is that this one
+is meant to be shown to the user and so should be used for the window titles,
+page headers and so on while the other one should be only used internally, e.g.
+for the file names or configuration file keys.
+
+By default, returns the same string as \helpref{GetVendorName}{wxappgetvendorname}.
+
+\newsince{2.9.0}
+
+
+\membersection{wxApp::GetVendorName}\label{wxappgetvendorname}
+
+\constfunc{wxString}{GetVendorName}{\void}
+
+Returns the application's vendor name.
+
+
+\membersection{wxApp::IsActive}\label{wxappisactive}
+
+\constfunc{bool}{IsActive}{\void}
+
+Returns \true if the application is active, i.e. if one of its windows is
+currently in the foreground. If this function returns \false and you need to
+attract users attention to the application, you may use 
+\helpref{wxTopLevelWindow::RequestUserAttention}{wxtoplevelwindowrequestuserattention} 
+to do it.
+
+
+\membersection{wxApp::IsMainLoopRunning}\label{wxappismainlooprunning}
+
+\func{static bool}{IsMainLoopRunning}{\void}
+
+Returns \true if the main event loop is currently running, i.e. if the
+application is inside \helpref{OnRun}{wxapponrun}.
+
+This can be useful to test whether events can be dispatched. For example,
+if this function returns \false, non-blocking sockets cannot be used because
+the events from them would never be processed.
+
+
+\membersection{wxApp::MacNewFile}\label{wxappmacnewfile}
+
+\func{void}{MacNewFile}{\void}
+
+Mac specific. Called in response of an "open-application" Apple event.
+Override this to create a new document in your app.
+
+\membersection{wxApp::MacOpenFile}\label{wxappmacopenfile}
+
+\func{void}{MacOpenFile}{\param{const wxString\& }{fileName}}
+
+Mac specific. Called in response of an "open-document" Apple event. You need to 
+override this method in order to open a document file after the
+user double clicked on it or if the document file was dropped
+on either the running application or the application icon in
+Finder.
+
+\membersection{wxApp::MacOpenURL}\label{wxappmacopenurl}
+
+\func{void}{MacOpenURL}{\param{const wxString\& }{url}}
 
-\membersection{wxApp::Initialized}\label{wxappinitialized}
+Mac specific. Called in response of a "get-url" Apple event.
 
-\func{bool}{Initialized}{\void}
+\membersection{wxApp::MacPrintFile}\label{wxappmacprintfile}
 
-Returns TRUE if the application has been initialized (i.e. if\rtfsp
-\helpref{wxApp::OnInit}{wxapponinit} has returned successfully).  This can be useful for error
-message routines to determine which method of output is best for the
-current state of the program (some windowing systems may not like
-dialogs to pop up before the main loop has been entered).
+\func{void}{MacPrintFile}{\param{const wxString\& }{fileName}}
+
+Mac specific. Called in response of a "print-document" Apple event.
+
+
+\membersection{wxApp::MacReopenApp}\label{wxappmacreopenapp}
+
+\func{void}{MacReopenApp}{\void}
+
+Mac specific. Called in response of a "reopen-application" Apple event.
 
 \membersection{wxApp::MainLoop}\label{wxappmainloop}
 
-\func{int}{MainLoop}{\void}
+\func{virtual int}{MainLoop}{\void}
 
-Called by wxWindows on creation of the application. Override this if you wish
+Called by wxWidgets on creation of the application. Override this if you wish
 to provide your own (environment-dependent) main loop.
 
 \wxheading{Return value}
 
 Returns 0 under X, and the wParam of the WM\_QUIT message under Windows.
 
-\membersection{wxApp::OnActivate}\label{wxapponactivate}
+%% VZ: OnXXX() functions should *not* be documented
+%%
+%%\membersection{wxApp::OnActivate}\label{wxapponactivate}
+%%
+%%\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}}
+%%
+%%Provide this member function to know whether the application is being
+%%activated or deactivated (Windows only).
+%%
+%%\wxheading{See also}
+%%
+%%\helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent}
+%%
+%%\membersection{wxApp::OnCharHook}\label{wxapponcharhook}
+%%
+%%\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
+%%
+%%This event handler function is called (under Windows only) to allow the window to intercept keyboard events
+%%before they are processed by child windows.
+%%
+%%\wxheading{Parameters}
+%%
+%%\docparam{event}{The keypress event.}
+%%
+%%\wxheading{Remarks}
+%%
+%%Use the wxEVT\_CHAR\_HOOK macro in your event table.
+%%
+%%If you use this member, you can selectively consume keypress events by calling\rtfsp
+%%\helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in.
+%%
+%%\wxheading{See also}
+%%
+%%\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
+%%\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
+
+
+\membersection{wxApp::OnAssertFailure}\label{wxapponassertfailure}
+
+\func{void}{OnAssertFailure}{\param{const wxChar }{*file}, \param{int }{line}, \param{const wxChar }{*func}, \param{const wxChar }{*cond}, \param{const wxChar }{*msg}}
+
+This function is called when an assert failure occurs, i.e. the condition
+specified in \helpref{wxASSERT}{wxassert} macro evaluated to {\tt false}.
+It is only called in debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) as
+asserts are not left in the release code at all.
+
+The base class version shows the default assert failure dialog box proposing to
+the user to stop the program, continue or ignore all subsequent asserts.
+
+\wxheading{Parameters}
 
-\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}}
+\docparam{file}{the name of the source file where the assert occurred}
 
-Provide this member function to know whether the application is being
-activated or deactivated (Windows only).
+\docparam{line}{the line number in this file where the assert occurred}
 
-\wxheading{See also}
+\docparam{func}{the name of the function where the assert occurred, may be
+empty if the compiler doesn't support C99 \texttt{\_\_FUNCTION\_\_}}
 
-\helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent}
+\docparam{cond}{the condition of the failed assert in text form}
 
-\membersection{wxApp::OnExit}\label{wxapponexit}
+\docparam{msg}{the message specified as argument to 
+\helpref{wxASSERT\_MSG}{wxassertmsg} or \helpref{wxFAIL\_MSG}{wxfailmsg}, will
+be {\tt NULL} if just \helpref{wxASSERT}{wxassert} or \helpref{wxFAIL}{wxfail} 
+was used}
 
-\func{int}{OnExit}{\void}
 
-Provide this member function for any processing which needs to be done as
-the application is about to exit.
+\membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror}
 
-\membersection{wxApp::OnCharHook}\label{wxapponcharhook}
+\func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}}
 
-\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
+Called when command line parsing fails (i.e. an incorrect command line option
+was specified by the user). The default behaviour is to show the program usage
+text and abort the program.
 
-This event handler function is called (under Windows only) to allow the window to intercept keyboard events
-before they are processed by child windows.
+Return {\tt true} to continue normal execution or {\tt false} to return 
+{\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program.
 
-\wxheading{Parameters}
+\wxheading{See also}
 
-\docparam{event}{The keypress event.}
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
 
-\wxheading{Remarks}
 
-Use the wxEVT\_CHAR\_HOOK macro in your event table.
+\membersection{wxApp::OnCmdLineHelp}\label{wxapponcmdlinehelp}
 
-If you use this member, you can selectively consume keypress events by calling\rtfsp
-\helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in.
+\func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}}
+
+Called when the help option ({\tt --help}) was specified on the command line.
+The default behaviour is to show the program usage text and abort the program.
+
+Return {\tt true} to continue normal execution or {\tt false} to return 
+{\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program.
 
 \wxheading{See also}
 
-\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
-\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
+
 
-\membersection{wxApp::OnIdle}\label{wxapponidle}
+\membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed}
 
-\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
+\func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}}
 
-Override this member function for any processing which needs to be done
-when the application is idle. You should call wxApp::OnIdle from your own function,
-since this forwards OnIdle events to windows and also performs garbage collection for
-windows whose destruction has been delayed.
+Called after the command line had been successfully parsed. You may override
+this method to test for the values of the various parameters which could be
+set from the command line.
 
-wxWindows' strategy for OnIdle processing is as follows. After pending user interface events for an
-application have all been processed, wxWindows sends an OnIdle event to the application object. wxApp::OnIdle itself
-sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
-their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
-caling \helpref{wxIdleEvent::ReqestMore}{wxidleeventrequestmore}, wxWindows will send another OnIdle
-event to the application object. This will occur in a loop until either a user event is found to be
-pending, or OnIdle requests no more time. Then all pending user events are processed until the system
-goes idle again, when OnIdle is called, and so on.
+Don't forget to call the base class version unless you want to suppress
+processing of the standard command line options.
+
+Return {\tt true} to continue normal execution or {\tt false} to return 
+{\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program.
 
 \wxheading{See also}
 
-\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
-\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
 
-\membersection{wxApp::OnEndSession}\label{wxapponendsession}
 
-\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}}
+\membersection{wxApp::OnExceptionInMainLoop}\label{wxapponexceptioninmainloop}
 
-This is an event handler function called when the operating system or GUI session is
-about to close down. The application has a chance to silently save information,
-and can optionally close itself.
+\func{virtual bool}{OnExceptionInMainLoop}{\void}
 
-Use the EVT\_END\_SESSION event table macro to handle query end session events.
+This function is called if an unhandled exception occurs inside the main
+application event loop. It can return \true to ignore the exception and to
+continue running the loop or \false to exit the loop and terminate the
+program. In the latter case it can also use C++ \texttt{throw} keyword to
+rethrow the current exception.
 
-The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument
-(forcing the application to close itself silently).
+The default behaviour of this function is the latter in all ports except under
+Windows where a dialog is shown to the user which allows him to choose between
+the different options. You may override this function in your class to do
+something more appropriate.
 
-\wxheading{Remarks}
+Finally note that if the exception is rethrown from here, it can be caught in 
+\helpref{OnUnhandledException}{wxapponunhandledexception}.
+
+
+\membersection{wxApp::OnExit}\label{wxapponexit}
+
+\func{virtual int}{OnExit}{\void}
+
+Override this member function for any processing which needs to be
+done as the application is about to exit. OnExit is called after
+destroying all application windows and controls, but before
+wxWidgets cleanup. Note that it is not called at all if 
+\helpref{OnInit}{wxapponinit} failed.
+
+The return value of this function is currently ignored, return the same value
+as returned by the base class method if you override it.
 
-Under X, OnEndSession is called in response to the 'die' event.
 
-Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message.
+\membersection{wxApp::OnFatalException}\label{wxapponfatalexception}
+
+\func{void}{OnFatalException}{\void}
+
+This function may be called if something fatal happens: an unhandled
+exception under Win32 or a a fatal signal under Unix, for example. However,
+this will not happen by default: you have to explicitly call 
+\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions} to enable this.
+
+Generally speaking, this function should only show a message to the user and
+return. You may attempt to save unsaved data but this is not guaranteed to
+work and, in fact, probably won't.
 
 \wxheading{See also}
 
-\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
-\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
-\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
-\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession}
+\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}
+
+%% VZ: the wxApp event handler are private and should not be documented here!
+%%
+%%\membersection{wxApp::OnIdle}\label{wxapponidle}
+%%
+%%\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
+%%
+%%Override this member function for any processing which needs to be done
+%%when the application is idle. You should call wxApp::OnIdle from your own function,
+%%since this forwards OnIdle events to windows and also performs garbage collection for
+%%windows whose destruction has been delayed.
+%%
+%%wxWidgets' strategy for OnIdle processing is as follows. After pending user interface events for an
+%%application have all been processed, wxWidgets sends an OnIdle event to the application object. wxApp::OnIdle itself
+%%sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
+%%their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
+%%calling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWidgets will send another OnIdle
+%%event to the application object. This will occur in a loop until either a user event is found to be
+%%pending, or OnIdle requests no more time. Then all pending user events are processed until the system
+%%goes idle again, when OnIdle is called, and so on.
+%%
+%%\wxheading{See also}
+%%
+%%\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
+%%\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
+%%
+%%\membersection{wxApp::OnEndSession}\label{wxapponendsession}
+%%
+%%\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}}
+%%
+%%This is an event handler function called when the operating system or GUI session is
+%%about to close down. The application has a chance to silently save information,
+%%and can optionally close itself.
+%%
+%%Use the EVT\_END\_SESSION event table macro to handle query end session events.
+%%
+%%The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a true argument
+%%(forcing the application to close itself silently).
+%%
+%%\wxheading{Remarks}
+%%
+%%Under X, OnEndSession is called in response to the `die' event.
+%%
+%%Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message.
+%%
+%%\wxheading{See also}
+%%
+%%\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
+%%\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
+%%\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
+
 
 \membersection{wxApp::OnInit}\label{wxapponinit}
 
 \func{bool}{OnInit}{\void}
 
 This must be provided by the application, and will usually create the
-application's main window, calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
+application's main window, optionally calling 
+\helpref{wxApp::SetTopWindow}{wxappsettopwindow}. You may use 
+\helpref{OnExit}{wxapponexit} to clean up anything initialized here, provided
+that the function returns \true.
 
-Return TRUE to continue processing, FALSE to exit the application.
+Notice that if you want to to use the command line processing provided by
+wxWidgets you have to call the base class version in the derived class
+OnInit().
 
-\membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession}
+Return \true to continue processing, \false to exit the application
+immediately.
 
-\func{void}{OnQueryEndSession}{\param{wxCloseEvent\& }{event}}
 
-This is an event handler function called when the operating system or GUI session is
-about to close down. Typically, an application will try to save unsaved documents
-at this point.
+\membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline}
 
-If \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns TRUE, the application
-is allowed to veto the shutdown by calling \helpref{wxCloseEvent::Veto}{wxcloseeventveto}.
-The application might veto the shutdown after prompting for documents to be saved, and the
-user has cancelled the save.
+\func{void}{OnInitCmdLine}{\param{wxCmdLineParser\& }{parser}}
 
-Use the EVT\_QUERY\_END\_SESSION event table macro to handle query end session events.
+Called from \helpref{OnInit}{wxapponinit} and may be used to initialize the
+parser with the command line options for this application. The base class
+versions adds support for a few standard options only.
 
-You should check whether the application is forcing the deletion of the window
-using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE,
-destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
-If not, it is up to you whether you respond by destroying the window.
+\membersection{wxApp::OnRun}\label{wxapponrun}
 
-The default handler calls \helpref{wxWindow::Close}{wxwindowclose} on the top-level window,
-and vetoes the shutdown if Close returns FALSE. This will be sufficient for many applications.
+\func{virtual int}{OnRun}{\void}
 
-\wxheading{Remarks}
+This virtual function is where the execution of a program written in wxWidgets
+starts. The default implementation just enters the main loop and starts
+handling the events until it terminates, either because 
+\helpref{ExitMainLoop}{wxappexitmainloop} has been explicitly called or because
+the last frame has been deleted and 
+\helpref{GetExitOnFrameDelete}{wxappgetexitonframedelete} flag is \true (this
+is the default).
 
-Under X, OnQueryEndSession is called in response to the 'save session' event.
+The return value of this function becomes the exit code of the program, so it
+should return $0$ in case of successful termination.
 
-Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message.
 
-\wxheading{See also}
+\membersection{wxApp::OnUnhandledException}\label{wxapponunhandledexception}
+
+\func{virtual void}{OnUnhandledException}{\void}
+
+This function is called when an unhandled C++ exception occurs inside 
+\helpref{OnRun()}{wxapponrun} (the exceptions which occur during the program
+startup and shutdown might not be caught at all). Notice that by now the main
+event loop has been terminated and the program will exit, if you want to
+prevent this from happening (i.e. continue running after catching an exception)
+you need to override \helpref{OnExceptionInMainLoop}{wxapponexceptioninmainloop}.
+
+The default implementation shows information about the exception in debug build
+but does nothing in the release build.
 
-\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
-\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
-\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
-\helpref{wxApp::OnEndSession}{wxapponendsession}
 
 \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage}
 
-\func{bool}{ProcessMessage}{\param{MSG *}{msg}}
+\func{bool}{ProcessMessage}{\param{WXMSG *}{msg}}
 
 Windows-only function for processing a message. This function
 is called from the main message loop, checking for windows that
-may wish to process it. The function returns TRUE if the message
-was processed, FALSE otherwise. If you use wxWindows with another class
+may wish to process it. The function returns true if the message
+was processed, false otherwise. If you use wxWidgets with another class
 library with its own message loop, you should make sure that this
-function is called to allow wxWindows to receive messages. For example,
-to allow co-existance with the Microsoft Foundation Classes, override
+function is called to allow wxWidgets to receive messages. For example,
+to allow co-existence with the Microsoft Foundation Classes, override
 the PreTranslateMessage function:
 
 \begin{verbatim}
-// Provide wxWindows message loop compatibility
+// Provide wxWidgets message loop compatibility
 BOOL CTheApp::PreTranslateMessage(MSG *msg)
 {
-  if (wxTheApp && wxTheApp->ProcessMessage(msg))
-    return TRUE;
+  if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
+    return true;
   else
     return CWinApp::PreTranslateMessage(msg);
 }
 \end{verbatim}
 
+
 \membersection{wxApp::Pending}\label{wxapppending}
 
-\func{bool}{Pending}{\void}
+\func{virtual bool}{Pending}{\void}
 
-Returns TRUE if unprocessed events are in the window system event queue
-(MS Windows and Motif).
+Returns true if unprocessed events are in the window system event queue.
 
 \wxheading{See also}
 
 \helpref{wxApp::Dispatch}{wxappdispatch}
 
-\membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
-
-\func{bool}{SendIdleEvents}{\void}
 
-Sends idle events to all top-level windows.
+\membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
 
-\func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}}
+\func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}, \param{wxIdleEvent\& }{event}}
 
 Sends idle events to a window and its children.
 
+Please note that this function is internal to wxWidgets and shouldn't be used
+by user code.
+
 \wxheading{Remarks}
 
 These functions poll the top-level windows, and their children, for idle event processing.
-If TRUE is returned, more OnIdle processing is requested by one or more window.
+If true is returned, more OnIdle processing is requested by one or more window.
 
 \wxheading{See also}
 
-\helpref{wxApp::OnIdle}{wxapponidle}, \helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent}
+\helpref{wxIdleEvent}{wxidleevent}
 
-\membersection{wxApp::SetAppName}\label{wxappsetappname}
 
-\func{void}{SetAppName}{\param{const wxString\& }{name}}
+\membersection{wxApp::SetAppDisplayName}\label{wxappsetappdisplayname}
 
-Sets the name of the application. The name may be used in dialogs
-(for example by the document/view framework). A default name is set by
-wxWindows.
+\func{void}{SetAppDisplayName}{\param{const wxString\& }{name}}
 
-\wxheading{See also}
+Set the application name to be used in the user-visible places such as window
+titles. See \helpref{GetAppDisplayName}{wxappgetappdisplayname} for more about
+the differences between the display name and name.
 
-\helpref{wxApp::GetAppName}{wxappgetappname}
-
-\membersection{wxApp::SetAuto3D}\label{wxappsetauto3d}
-
-\func{void}{SetAuto3D}{\param{const bool}{ auto3D}}
 
-Switches automatic 3D controls on or off.
-
-\wxheading{Parameters}
+\membersection{wxApp::SetAppName}\label{wxappsetappname}
 
-\docparam{auto3D}{If TRUE, all controls will be created with 3D appearances unless
-overridden for a control or dialog. The default is TRUE}
+\func{void}{SetAppName}{\param{const wxString\& }{name}}
 
-\wxheading{Remarks}
+Sets the name of the application. This name should be used for file names,
+configuration file entries and other internal strings. For the user-visible
+strings, such as the window titles, the application display name set by 
+\helpref{SetAppDisplayName}{wxappsetappdisplayname} is used instead.
 
-This has an effect on Windows only.
+By default the application name is set to the name of its executable file.
 
 \wxheading{See also}
 
-\helpref{wxApp::GetAuto3D}{wxappgetauto3d}
+\helpref{wxApp::GetAppName}{wxappgetappname}
+
 
 \membersection{wxApp::SetClassName}\label{wxappsetclassname}
 
@@ -403,47 +699,51 @@ manner to refer to the application.
 
 \helpref{wxApp::GetClassName}{wxappgetclassname}
 
-\membersection{wxApp::SetExitOnDelete}\label{wxappsetexitondelete}
 
-\func{void}{SetExitOnDelete}{\param{bool}{ flag}}
+\membersection{wxApp::SetExitOnFrameDelete}\label{wxappsetexitonframedelete}
+
+\func{void}{SetExitOnFrameDelete}{\param{bool}{ flag}}
 
 Allows the programmer to specify whether the application will exit when the
 top-level frame is deleted.
 
 \wxheading{Parameters}
 
-\docparam{flag}{If TRUE (the default), the application will exit when the top-level frame is
-deleted. If FALSE, the application will continue to run.}
+\docparam{flag}{If true (the default), the application will exit when the top-level frame is
+deleted. If false, the application will continue to run.}
 
-\wxheading{Remarks}
+\wxheading{See also}
+
+\helpref{wxApp::GetExitOnFrameDelete}{wxappgetexitonframedelete},\\
+\helpref{wxApp shutdown overview}{wxappshutdownoverview}
 
-Currently, setting this to FALSE only has an effect under Windows.
 
-\membersection{wxApp::SetPrintMode}\label{wxappsetprintmode}
+\membersection{wxApp::SetInstance}\label{wxappsetinstance}
 
-\func{void}{SetPrintMode}{\param{int}{ mode}}
+\func{static void}{SetInstance}{\param{wxAppConsole* }{app}}
 
-Sets the print mode determining what printing facilities will be
-used by the printing framework.
+Allows external code to modify global \texttt{wxTheApp}, but you should really
+know what you're doing if you call it.
 
 \wxheading{Parameters}
 
-\docparam{mode}{This can be one of:
+\docparam{app}{Replacement for the global application object.}
+
+\wxheading{See also}
+
+\helpref{wxApp::GetInstance}{wxappgetinstance}
 
-\begin{twocollist}\itemsep=0pt
-\twocolitem{{\bf wxPRINT\_WINDOWS}}{Under Windows, use Windows printing (wxPrinterDC). This is the
-default under Windows.}
-\twocolitem{{\bf wxPRINT\_POSTSCRIPT}}{Use PostScript printing (wxPostScriptDC). This is the
-default for non-Windows platforms.}
-\end{twocollist}
-}%
 
 \membersection{wxApp::SetTopWindow}\label{wxappsettopwindow}
 
 \func{void}{SetTopWindow}{\param{wxWindow* }{window}}
 
-Sets the `top' window. You should normally call this from within \helpref{wxApp::OnInit}{wxapponinit} to
-let wxWindows know which is the main window.
+Sets the `top' window. You can call this from within \helpref{wxApp::OnInit}{wxapponinit} to
+let wxWidgets know which is the main window. You don't have to set the top window;
+it is only a convenience so that (for example) certain dialogs without parents can use a
+specific window as the top window. If no top window is specified by the application,
+wxWidgets just uses the first frame or dialog in its top-level window list, when it
+needs to use the top window.
 
 \wxheading{Parameters}
 
@@ -453,3 +753,85 @@ let wxWindows know which is the main window.
 
 \helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit}
 
+
+\membersection{wxApp::SetVendorDisplayName}\label{wxappsetvendordisplayname}
+
+\func{void}{SetVendorDisplayName}{\param{const wxString\& }{name}}
+
+Set the vendor name to be used in the user-visible places. See
+\helpref{GetVendorDisplayName}{wxappgetvendordisplayname} for more about
+the differences between the display name and name.
+
+
+\membersection{wxApp::SetVendorName}\label{wxappsetvendorname}
+
+\func{void}{SetVendorName}{\param{const wxString\& }{name}}
+
+Sets the name of application's vendor. The name will be used
+in registry access. A default name is set by
+wxWidgets.
+
+\wxheading{See also}
+
+\helpref{wxApp::GetVendorName}{wxappgetvendorname}
+
+
+\membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual}
+
+\func{void}{SetUseBestVisual}{\param{bool}{ flag}, \param{bool}{ forceTrueColour = false}}
+
+Allows the programmer to specify whether the application will use the best visual
+on systems that support several visual on the same display. This is typically the
+case under Solaris and IRIX, where the default visual is only 8-bit whereas certain
+applications are supposed to run in TrueColour mode.
+
+If \arg{forceTrueColour} is true then the application will try to force
+using a TrueColour visual and abort the app if none is found.
+
+Note that this function has to be called in the constructor of the {\tt wxApp} 
+instance and won't have any effect when called later on.
+
+This function currently only has effect under GTK.
+
+\wxheading{Parameters}
+
+\docparam{flag}{If true, the app will use the best visual.}
+
+
+\membersection{wxApp::HandleEvent}\label{wxapphandleevent}
+
+\constfunc{virtual void}{HandleEvent}{\param{wxEvtHandler}{ *handler}, \param{wxEventFunction}{ func}, \param{wxEvent\& }{event}}
+
+This function simply invokes the given method \arg{func} of the specified
+event handler \arg{handler} with the \arg{event} as parameter. It exists solely
+to allow to catch the C++ exceptions which could be thrown by all event
+handlers in the application in one place: if you want to do this, override this
+function in your wxApp-derived class and add try/catch clause(s) to it.
+
+
+\membersection{wxApp::Yield}\label{wxappyield}
+
+\func{bool}{Yield}{\param{bool}{ onlyIfNeeded = false}}
+
+Yields control to pending messages in the windowing system. This can be useful, for example, when a
+time-consuming process writes to a text window. Without an occasional
+yield, the text window will not be updated properly, and on systems with
+cooperative multitasking, such as Windows 3.1 other processes will not respond.
+
+Caution should be exercised, however, since yielding may allow the
+user to perform actions which are not compatible with the current task.
+Disabling menu items or whole menus during processing can avoid unwanted
+reentrance of code: see \helpref{::wxSafeYield}{wxsafeyield} for a better
+function.
+
+Note that Yield() will not flush the message logs. This is intentional as
+calling Yield() is usually done to quickly update the screen and popping up a
+message box dialog may be undesirable. If you do wish to flush the log
+messages immediately (otherwise it will be done during the next idle loop
+iteration), call \helpref{wxLog::FlushActive}{wxlogflushactive}.
+
+Calling Yield() recursively is normally an error and an assert failure is
+raised in debug build if such situation is detected. However if the 
+{\it onlyIfNeeded} parameter is {\tt true}, the method will just silently
+return {\tt false} instead.
+
