X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bf188f1add12abe2238d51d0568acc2a386e8051..d30ff492f0ee23d067e996c0a5f769e4dafb0225:/docs/latex/wx/app.tex diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex index 4ccfd04f3b..f4e827c960 100644 --- a/docs/latex/wx/app.tex +++ b/docs/latex/wx/app.tex @@ -85,6 +85,17 @@ This can be used for programming event loops, e.g. \helpref{wxApp::Pending}{wxapppending} +\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::GetAppName}\label{wxappgetappname} \constfunc{wxString}{GetAppName}{\void} @@ -189,46 +200,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} @@ -399,13 +435,13 @@ Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSIO \wxheading{See also} \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} -\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 @@ -420,7 +456,7 @@ the PreTranslateMessage function: // Provide wxWindows message loop compatibility BOOL CTheApp::PreTranslateMessage(MSG *msg) { - if (wxTheApp && wxTheApp->ProcessMessage(msg)) + if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg)) return TRUE; else return CWinApp::PreTranslateMessage(msg); @@ -454,7 +490,9 @@ 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{wxIdleEvent}{wxidleevent} \membersection{wxApp::SetAppName}\label{wxappsetappname} @@ -542,20 +580,6 @@ wxWindows. \helpref{wxApp::GetVendorName}{wxappgetvendorname} -\membersection{wxApp::GetStdIcon}\label{wxappgetstdicon} - -\func{virtual wxIcon}{GetStdIcon}{\param{int }{which}} const - -Returns the icons used by wxWindows internally, e.g. the ones used for -message boxes. This function is used internally and -can be overridden by the user to change the default icons. - -\wxheading{Parameters} - -\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}} @@ -574,3 +598,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. +