Some work on GTK focus handling and events.

[wxWidgets.git] / docs / latex / wx / app.tex

diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex
index 4ccfd04f3bb60d362bc956b606ac84f9aa32fede..b830069460c24716842917986353ef5a797fab96 100644 (file)
--- 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.
 
 
 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}
 
 
 \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}
 
 
 \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{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}
 
 
 \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}
 
 
 \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}
 
 
 \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.}
 
 
 \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.
+