add events API to wxHtmlWindow (patch #1504493 by Francesco Montorsi)

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

diff --git a/docs/latex/wx/closeevt.tex b/docs/latex/wx/closeevt.tex
index d41ff76c48805489cd86a41335deacb2d1255aa2..abb81d7e874f76bb25b9328848b6562d9a16e60b 100644 (file)
--- a/docs/latex/wx/closeevt.tex
+++ b/docs/latex/wx/closeevt.tex
@@ -2,10 +2,28 @@
 
 This event class contains information about window and session close events.
 
 
 This event class contains information about window and session close events.
 

+The handler function for EVT\_CLOSE is called when the user has tried to close a a frame
+or dialog box using the window manager (X) or system menu (Windows). It can
+also be invoked by the application itself programmatically, for example by
+calling the \helpref{wxWindow::Close}{wxwindowclose} function.
+
+You should check whether the application is forcing the deletion of the window
+using \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto}. If this is {\tt false},
+you {\it must} destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
+If the return value is true, it is up to you whether you respond by destroying the window.
+
+If you don't destroy the window, you should call \helpref{wxCloseEvent::Veto}{wxcloseeventveto} to
+let the calling code know that you did not destroy the window. This allows the \helpref{wxWindow::Close}{wxwindowclose} function
+to return {\tt true} or {\tt false} depending on whether the close instruction was honoured or not.
+

 \wxheading{Derived from}
 
 \helpref{wxEvent}{wxevent}
 
 \wxheading{Derived from}
 
 \helpref{wxEvent}{wxevent}
 

+\wxheading{Include files}
+
+<wx/event.h>
+

 \wxheading{Event table macros}
 
 To process a close event, use these event handler macros to direct input to member
 \wxheading{Event table macros}
 
 To process a close event, use these event handler macros to direct input to member


@@ -13,45 +31,78 @@ functions that take a wxCloseEvent argument.
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt

-\twocolitem{{\bf EVT\_CLOSE(func)}}{Process a close event, supplying the member function.}
+\twocolitem{{\bf EVT\_CLOSE(func)}}{Process a close event, supplying the member function. This
+event applies to wxFrame and wxDialog classes.}
+\twocolitem{{\bf EVT\_QUERY\_END\_SESSION(func)}}{Process a query end session event, supplying the member function.
+This event applies to wxApp only.}
+\twocolitem{{\bf EVT\_END\_SESSION(func)}}{Process an end session event, supplying the member function.
+This event applies to wxApp only.}

 \end{twocollist}%
 
 \wxheading{See also}
 
 \end{twocollist}%
 
 \wxheading{See also}
 

-\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp

 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp

+%% GD: OnXXX functions are not documented
+%%\helpref{wxApp::OnEndSession}{wxapponendsession},\rtfsp

 \helpref{Window deletion overview}{windowdeletionoverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \helpref{Window deletion overview}{windowdeletionoverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxCloseEvent::wxCloseEvent}
+
+\membersection{wxCloseEvent::wxCloseEvent}\label{wxcloseeventctor}

 
 \func{}{wxCloseEvent}{\param{WXTYPE}{ commandEventType = 0}, \param{int}{ id = 0}}
 
 Constructor.
 
 
 \func{}{wxCloseEvent}{\param{WXTYPE}{ commandEventType = 0}, \param{int}{ id = 0}}
 
 Constructor.
 

+
+\membersection{wxCloseEvent::CanVeto}\label{wxcloseeventcanveto}
+
+\func{bool}{CanVeto}{\void}
+
+Returns true if you can veto a system shutdown or a window close event.
+Vetoing a window close event is not possible if the calling code wishes to
+force the application to exit, and so this function must be called to check this.
+
+

 \membersection{wxCloseEvent::GetLoggingOff}\label{wxcloseeventgetloggingoff}
 
 \constfunc{bool}{GetLoggingOff}{\void}
 
 \membersection{wxCloseEvent::GetLoggingOff}\label{wxcloseeventgetloggingoff}
 
 \constfunc{bool}{GetLoggingOff}{\void}
 

-Returns TRUE if the user is logging off.
+Returns true if the user is just logging off or false if the system is
+shutting down. This method can only be called for end session and query end
+session events, it doesn't make sense for close window event.
+
+
+\membersection{wxCloseEvent::SetCanVeto}\label{wxcloseeventsetcanveto}
+
+\func{void}{SetCanVeto}{\param{bool}{ canVeto}}
+
+Sets the 'can veto' flag.

 
 

-\membersection{wxCloseEvent::GetSessionEnding}\label{wxcloseeventgetsessionending}

 
 

-\constfunc{bool}{GetSessionEnding}{\void}
+\membersection{wxCloseEvent::SetForce}\label{wxcloseeventsetforce}

 
 

-Returns TRUE if the session is ending.
+\constfunc{void}{SetForce}{\param{bool}{ force}}

 
 

-\membersection{wxCloseEvent::GetForce}\label{wxcloseeventgetforce}
+Sets the 'force' flag.

 
 

-\constfunc{void}{GetForce}{\void}

 
 

-Returns TRUE if the application wishes to force the window to close.
+\membersection{wxCloseEvent::SetLoggingOff}\label{wxcloseeventsetloggingoff}
+
+\constfunc{void}{SetLoggingOff}{\param{bool}{ loggingOff}}
+
+Sets the 'logging off' flag.
+

 
 \membersection{wxCloseEvent::Veto}\label{wxcloseeventveto}
 
 
 \membersection{wxCloseEvent::Veto}\label{wxcloseeventveto}
 

-\func{void}{Veto}{\void}
+\func{void}{Veto}{\param{bool}{ veto = true}}
+
+Call this from your event handler to veto a system shutdown or to signal
+to the calling application that a window close did not happen.

 
 

-Call this from your event handler to veto a system shutdown.
+You can only veto a shutdown if \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns
+true.