X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8480b297e70a29b785421ded6db22ae024e35038..e195c8c95fb154d035bab400952fc81c62439549:/docs/latex/wx/app.tex?ds=sidebyside

diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex
index 54648146b3..386f8530f6 100644
--- a/docs/latex/wx/app.tex
+++ b/docs/latex/wx/app.tex
@@ -38,9 +38,6 @@ a reference to your application object) to be visible to other files.
 
 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}}
 
 \func{void}{\destruct{wxApp}}{\void}
@@ -133,7 +130,7 @@ otherwise.
 
 \membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}
 
-\constfunc{wxWindow *}{GetTopWindow}{\void}
+\constfunc{virtual wxWindow *}{GetTopWindow}{\void}
 
 Returns a pointer to the top window.
 
@@ -150,13 +147,19 @@ function will find the first top-level window (frame or dialog) and return that.
 
 \constfunc{bool}{GetUseBestVisual}{\void}
 
-Returns TRUE if the application will use the best visual on system that support
+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::GetVendorName}\label{wxappgetvendorname}
+
+\constfunc{wxString}{GetVendorName}{\void}
+
+Returns the application's vendor name.
+
 \membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
 
 \func{void}{ExitMainLoop}{\void}
@@ -186,16 +189,64 @@ to provide your own (environment-dependent) main loop.
 
 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::OnAssert}\label{wxapponassert}
+
+\func{void}{OnAssert}{\param{const wxChar }{*file}, \param{int }{line}, \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 show the default assert failure dialog box proposing to
+the user to stop the program, continue or ignore all subsequent asserts.
 
-\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}}
+\wxheading{Parameters}
 
-Provide this member function to know whether the application is being
-activated or deactivated (Windows only).
+\docparam{file}{the name of the source file where the assert occured}
 
-\wxheading{See also}
+\docparam{line}{the line number in this file where the assert occured}
 
-\helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent}
+\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}
 
 \membersection{wxApp::OnExit}\label{wxapponexit}
 
@@ -204,87 +255,143 @@ activated or deactivated (Windows only).
 Provide this member function for any processing which needs to be done as
 the application is about to exit.
 
-\membersection{wxApp::OnCharHook}\label{wxapponcharhook}
-
-\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
+\membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror}
 
-This event handler function is called (under Windows only) to allow the window to intercept keyboard events
-before they are processed by child windows.
+\func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}}
 
-\wxheading{Parameters}
+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.
 
-\docparam{event}{The keypress event.}
+Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return 
+{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program.
 
-\wxheading{Remarks}
+\wxheading{See also}
 
-Use the wxEVT\_CHAR\_HOOK macro in your event table.
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
 
-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.
+\membersection{wxApp::OnCmdLineHelp}\label{wxapponcmdlinehelp}
 
-\wxheading{See also}
+\func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}}
 
-\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
-\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
+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.
 
-\membersection{wxApp::OnIdle}\label{wxapponidle}
+Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return 
+{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program.
 
-\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}
+\wxheading{See also}
 
-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.
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
 
-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.
+\membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed}
 
-\wxheading{See also}
+\func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}}
 
-\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp
-\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents}
+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.
 
-\membersection{wxApp::OnEndSession}\label{wxapponendsession}
+Don't forget to call the base class version unless you want to suppress
+processing of the standard command line options.
 
-\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}}
+Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return 
+{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program.
 
-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.
+\wxheading{See also}
 
-Use the EVT\_END\_SESSION event table macro to handle query end session events.
+\helpref{OnInitCmdLine}{wxapponinitcmdline}
 
-The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument
-(forcing the application to close itself silently).
+\membersection{wxApp::OnFatalException}\label{wxapponfatalexception}
 
-\wxheading{Remarks}
+\func{void}{OnFatalException}{\void}
 
-Under X, OnEndSession is called in response to the 'die' event.
+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.
 
-Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message.
+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{wxHandleFatalExcetions}{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.
+%%
+%%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::RequestMore}{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.
+%%
+%%\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
+%%\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession}
 
 \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, optionally calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
+application's main window, optionally calling 
+\helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
+
+Notice that if you want to to use the command line processing provided by
+wxWindows you have to call the base class version in the derived class
+OnInit().
 
 Return TRUE to continue processing, FALSE to exit the application.
 
+\membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline}
+
+\func{void}{OnInitCmdLine}{\param{wxCmdLineParser\& }{parser}}
+
+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.
+
 \membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession}
 
 \func{void}{OnQueryEndSession}{\param{wxCloseEvent\& }{event}}
@@ -310,7 +417,7 @@ and vetoes the shutdown if Close returns FALSE. This will be sufficient for many
 
 \wxheading{Remarks}
 
-Under X, OnQueryEndSession is called in response to the 'save session' event.
+Under X, OnQueryEndSession is called in response to the `save session' event.
 
 Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message.
 
@@ -434,7 +541,7 @@ deleted. If FALSE, the application will continue to run.}
 
 Sets the `top' window. You can call this from within \helpref{wxApp::OnInit}{wxapponinit} to
 let wxWindows know which is the main window. You don't have to set the top window;
-it's only a convenience so that (for example) certain dialogs without parents can use a
+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,
 wxWindows just uses the first frame or dialog in its top-level window list, when it
 needs to use the top window.
@@ -447,6 +554,19 @@ needs to use the top window.
 
 \helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit}
 
+
+\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
+wxWindows.
+
+\wxheading{See also}
+
+\helpref{wxApp::GetVendorName}{wxappgetvendorname}
+
 \membersection{wxApp::GetStdIcon}\label{wxappgetstdicon}
 
 \func{virtual wxIcon}{GetStdIcon}{\param{int }{which}} const
@@ -457,18 +577,20 @@ can be overridden by the user to change the default icons.
 
 \wxheading{Parameters}
 
-\docparam{which}{One of the wxICON\_XXX defines and chooses which icon to return.}
+\docparam{which}{One of the wxICON\_XXX specifies which icon to return.}
+
+See \helpref{wxMessageBox}{wxmessagebox} for a list of icon identifiers.
 
 \membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual}
 
 \func{void}{SetUseBestVisual}{\param{bool}{ flag}}
 
 Allows the programmer to specify whether the application will use the best visual
-on system 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 but some apps
-are supposed to run in TrueColour mode.
+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
+appications are supposed to run in TrueColour mode.
 
-Note that this function has to be called in the constructor of the {\tt wxApp}
+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.
@@ -476,3 +598,4 @@ This function currently only has effect under GTK.
 \wxheading{Parameters}
 
 \docparam{flag}{If TRUE, the app will use the best visual.}
+
