Session management changes for wxMSW.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@820 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/app.tex

@@ -238,6 +238,32 @@ goes idle again, when OnIdle is called, and so on.
 \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}{wxappqueryonendsession}
+
 \membersection{wxApp::OnInit}\label{wxapponinit}
 
 \func{bool}{OnInit}{\void}
@@ -247,16 +273,43 @@ application's main window, calling \helpref{wxApp::SetTopWindow}{wxappsettopwind
 
 Return TRUE to continue processing, FALSE to exit the application.
 
-\membersection{wxApp::Pending}\label{wxapppending}
+\membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession}
 
-\func{bool}{Pending}{\void}
+\func{void}{OnQueryEndSession}{\param{wxCloseEvent\& }{event}}
 
-Returns TRUE if unprocessed events are in the window system event queue
-(MS Windows and Motif).
+This is an event handler function called when the operating system or GUI session is
+about to close down. Typically, an application will try to save unsaved documents
+at this point.
+
+If \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns TRUE, the application
+is allowed to veto the shutdown by calling \helpref{wxCloseEvent::Veto}{wxcloseeventveto}.
+The application might veto the shutdown after prompting for documents to be saved, and the
+user has cancelled the save.
+
+Use the EVT\_QUERY\_END\_SESSION event table macro to handle query end session events.
+
+You should check whether the application is forcing the deletion of the window
+using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE,
+destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
+If not, it is up to you whether you respond by destroying the window.
+
+The default handler calls \helpref{wxWindow::Close}{wxwindowclose} on the top-level window,
+and vetoes the shutdown if Close returns FALSE. This will be sufficient for many applications.
+
+\wxheading{Remarks}
+
+Under X, OnQueryEndSession is called in response to the 'save session' event.
+
+Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message.
 
 \wxheading{See also}
 
-\helpref{wxApp::Dispatch}{wxappdispatch}
+\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
+\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
+\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
+\helpref{wxApp::OnEndSession}{wxapponendsession}
+
+\membersection{wxWindow::OnScroll}\label{wxwindowonscroll}
 
 \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage}
 
@@ -282,6 +335,17 @@ BOOL CTheApp::PreTranslateMessage(MSG *msg)
 }
 \end{verbatim}
 
+\membersection{wxApp::Pending}\label{wxapppending}
+
+\func{bool}{Pending}{\void}
+
+Returns TRUE if unprocessed events are in the window system event queue
+(MS Windows and Motif).
+
+\wxheading{See also}
+
+\helpref{wxApp::Dispatch}{wxappdispatch}
+
 \membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
 
 \func{bool}{SendIdleEvents}{\void}

docs/latex/wx/closeevt.tex

@@ -13,13 +13,20 @@ functions that take a wxCloseEvent argument.
 
 \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}
 
 \helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
+\helpref{wxApp::OnQueryEndSession}{wxappqueryendsession},\rtfsp
+\helpref{wxApp::OnEndSession}{wxappendsession},\rtfsp
 \helpref{Window deletion overview}{windowdeletionoverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
@@ -30,6 +37,14 @@ functions that take a wxCloseEvent argument.
 
 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}
@@ -44,14 +59,37 @@ Returns TRUE if the session is ending.
 
 \membersection{wxCloseEvent::GetForce}\label{wxcloseeventgetforce}
 
-\constfunc{void}{GetForce}{\void}
+\constfunc{bool}{GetForce}{\void}
 
 Returns TRUE if the application wishes to force the window to close.
+This will shortly be obsolete, replaced by CanVeto.
+
+\membersection{wxCloseEvent::SetCanVeto}\label{wxcloseeventsetcanveto}
+
+\func{void}{SetCanVeto}{\param{bool}{ canVeto}}
+
+Sets the 'can veto' flag.
+
+\membersection{wxCloseEvent::SetForce}\label{wxcloseeventsetforce}
+
+\constfunc{void}{SetForce}{\param{bool}{ force}}
+
+Sets the 'force' flag.
+
+\membersection{wxCloseEvent::SetLoggingOff}\label{wxcloseeventsetloggingoff}
+
+\constfunc{void}{SetLoggingOff}{\param{bool}{ loggingOff}}
+
+Sets the 'logging off' flag.
 
 \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.
+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.
+
+You can only veto a shutdown if \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns
+TRUE.
 
 

docs/latex/wx/window.tex

@@ -185,6 +185,60 @@ Applies to managed windows (wxFrame and wxDialog classes) only.
 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
 \helpref{wxCloseEvent}{wxcloseevent}
 
+\membersection{wxWindow::ConvertDialogToPixels}\label{wxwindowconvertdialogtopixels}
+
+\func{wxPoint}{ConvertDialogToPixels}{\param{const wxPoint\&}{ pt}}
+
+\func{wxSize}{ConvertDialogToPixels}{\param{const wxSize\&}{ sz}}
+
+Converts a point or size from dialog units to pixels.
+
+For the x dimension, the dialog units are multiplied by the average character width
+and then divided by 4.
+
+For the y dimension, the dialog units are multiplied by the average character height
+and then divided by 8.
+
+\wxheading{Remarks}
+
+Dialog units are used for maintaining a dialog's proportions even if the font changes.
+Dialogs created using Dialog Editor optionally use dialog units.
+
+You can also use these functions programmatically. A convenience macro is defined:
+
+{\small
+\begin{verbatim}
+#define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
+\end{verbatim}
+}
+
+\wxheading{See also}
+
+\helpref{wxWindow::ConvertPixelsToDialog}{wxwindowconvertpixelstodialog}
+
+\membersection{wxWindow::ConvertPixelsToDialog}\label{wxwindowconvertpixelstodialog}
+
+\func{wxPoint}{ConvertPixelsToDialog}{\param{const wxPoint\&}{ pt}}
+
+\func{wxSize}{ConvertPixelsToDialog}{\param{const wxSize\&}{ sz}}
+
+Converts a point or size from pixels to dialog units.
+
+For the x dimension, the pixels are multiplied by 4 and then divided by the average
+character width.
+
+For the y dimension, the pixels are multipled by 8 and then divided by the average
+character height.
+
+\wxheading{Remarks}
+
+Dialog units are used for maintaining a dialog's proportions even if the font changes.
+Dialogs created using Dialog Editor optionally use dialog units.
+
+\wxheading{See also}
+
+\helpref{wxWindow::ConvertDialogToPixels}{wxwindowconvertdialogtopixels}
+
 \membersection{wxWindow::Destroy}\label{wxwindowdestroy}
 
 \func{virtual bool}{Destroy}{\void}
@@ -811,7 +865,7 @@ you may delete other windows.
 
 \wxheading{Remarks}
 
-Derive your own class to handle this message. The default handler returns FALSE.
+Derive your own class to handle this message. The default handler returns TRUE.
 
 \wxheading{See also}
 
@@ -836,6 +890,14 @@ using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE,
 destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
 If not, it is up to you whether you respond by destroying the window.
 
+(Note: GetForce is now superceded by CanVeto. So to test whether forced destruction of
+the window is required, test for the negative of CanVeto. If CanVeto returns FALSE,
+it is not possible to skip window deletion.)
+
+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 TRUE or FALSE depending on whether the close instruction was honoured or not.
+
 \wxheading{Remarks}
 
 The \helpref{wxWindow::OnClose}{wxwindowonclose} virtual function remains
@@ -849,7 +911,9 @@ destroying the window if it returns TRUE or if the close is being forced.
 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
 \helpref{wxWindow::OnClose}{wxwindowonclose},\rtfsp
 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
-\helpref{wxCloseEvent}{wxcloseevent}
+\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
+\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession},\rtfsp
+\helpref{wxApp::OnEndSession}{wxapponendsession}
 
 \membersection{wxWindow::OnDropFiles}\label{wxwindowondropfiles}
 
@@ -1124,8 +1188,6 @@ void MyWindow::OnPaint(wxPaintEvent& event)
 \helpref{wxPaintDC}{wxpaintdc},\rtfsp
 \helpref{Event handling overview}{eventhandlingoverview}
 
-\membersection{wxWindow::OnScroll}\label{wxwindowonscroll}
-
 \func{void}{OnScroll}{\param{wxScrollEvent\& }{event}}
 
 Called when a scroll event is received from one of the window's built-in scrollbars.