X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bf188f1add12abe2238d51d0568acc2a386e8051..df22f86063643de23dd02c2a77217d07b1918be1:/docs/latex/wx/app.tex diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex index 4ccfd04f3b..b830069460 100644 --- a/docs/latex/wx/app.tex +++ b/docs/latex/wx/app.tex @@ -189,46 +189,71 @@ 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} - -\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::OnExit}\label{wxapponexit} - -\func{int}{OnExit}{\void} +%% 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} -Provide this member function for any processing which needs to be done as -the application is about to exit. +\membersection{wxApp::OnAssert}\label{wxapponassert} -\membersection{wxApp::OnCharHook}\label{wxapponcharhook} +\func{void}{OnAssert}{\param{const wxChar }{*file}, \param{int }{line}, \param{const wxChar }{*msg}} -\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} +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. -This event handler function is called (under Windows only) to allow the window to intercept keyboard events -before they are processed by child windows. +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. \wxheading{Parameters} -\docparam{event}{The keypress event.} +\docparam{file}{the name of the source file where the assert occured} -\wxheading{Remarks} +\docparam{line}{the line number in this file where the assert occured} -Use the wxEVT\_CHAR\_HOOK macro in your event table. +\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} -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::OnExit}\label{wxapponexit} -\wxheading{See also} +\func{int}{OnExit}{\void} -\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp -\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook} +Provide this member function for any processing which needs to be done as +the application is about to exit. \membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror} @@ -400,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} @@ -454,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} @@ -574,3 +603,29 @@ This function currently only has effect under GTK. \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. +