X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8480b297e70a29b785421ded6db22ae024e35038..a9249b2eb2a40d8c71f828669045c4ddaa8dc5ff:/docs/latex/wx/app.tex diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex index 54648146b3..b830069460 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} +\membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror} -\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} +\func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}} -This event handler function is called (under Windows only) to allow the window to intercept keyboard events -before they are processed by child windows. +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. -\wxheading{Parameters} +Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return +{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program. -\docparam{event}{The keypress event.} +\wxheading{See also} -\wxheading{Remarks} +\helpref{OnInitCmdLine}{wxapponinitcmdline} -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}} -\wxheading{See also} +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. -\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp -\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook} +Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return +{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program. -\membersection{wxApp::OnIdle}\label{wxapponidle} +\wxheading{See also} -\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}} +\helpref{OnInitCmdLine}{wxapponinitcmdline} -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. +\membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed} -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. +\func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}} -\wxheading{See also} +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. -\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp -\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents} +Don't forget to call the base class version unless you want to suppress +processing of the standard command line options. -\membersection{wxApp::OnEndSession}\label{wxapponendsession} +Return {\tt TRUE} to continue normal execution or {\tt FALSE} to return +{\tt FALSE} from \helpref{OnInit}{wxapponinit} thus terminating the program. -\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}} +\wxheading{See also} -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. +\helpref{OnInitCmdLine}{wxapponinitcmdline} -Use the EVT\_END\_SESSION event table macro to handle query end session events. +\membersection{wxApp::OnFatalException}\label{wxapponfatalexception} -The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument -(forcing the application to close itself silently). +\func{void}{OnFatalException}{\void} -\wxheading{Remarks} +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 X, OnEndSession is called in response to the 'die' event. - -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. @@ -318,8 +425,9 @@ Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSIO \helpref{wxWindow::Close}{wxwindowclose},\rtfsp \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp -\helpref{wxCloseEvent}{wxcloseevent},\rtfsp -\helpref{wxApp::OnEndSession}{wxapponendsession} +\helpref{wxCloseEvent}{wxcloseevent} +%% GD: OnXXX functions are not documented +%%\helpref{wxApp::OnEndSession}{wxapponendsession} \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage} @@ -372,7 +480,10 @@ 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} +%% GD: OnXXX functions are not documented +%%\helpref{wxApp::OnIdle}{wxapponidle} +\helpref{wxWindow::OnIdle}{wxwindowonidle},\rtfsp +\helpref{wxIdleEvent}{wxidleevent} \membersection{wxApp::SetAppName}\label{wxappsetappname} @@ -434,7 +545,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 +558,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 +581,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 +602,30 @@ This function currently only has effect under GTK. \wxheading{Parameters} \docparam{flag}{If TRUE, the app will use the best visual.} + +\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 the +{\it onlyIfNeeded} parameter is {\tt TRUE}, the method will just silently +return {\tt FALSE} instead. +