1. wxNotifyEvent documented

2. wxNotebook event now derives from it under wxGTK too - fixing the
   PAGE_CHANGING event handling bug
3. the controls sample demonstrates PAGE_CHANGING in action


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

docs/latex/wx/classes.tex

@@ -122,6 +122,7 @@
 \input node.tex
 \input notebook.tex
 \input noteevt.tex
+\input notifevt.tex
 \input object.tex
 \input outptstr.tex
 \input pagedlg.tex

docs/latex/wx/noteevt.tex

@@ -1,9 +1,24 @@
 \section{\class{wxNotebookEvent}}\label{wxnotebookevent}
 
-This class represents the events generated by a notebook control.
+This class represents the events generated by a notebook control: currently,
+there are two of them. The PAGE\_CHANGING event is sent before the current
+page is changed. It allows to the program to examine the current page (which
+can be retrieved with 
+\helpref{GetOldSelection()}wxnotebookeventgetoldselection}) and to veto the page
+change by calling \helpref{Veto()}{wxnotifyeventveto} if, for example, the
+current values in the controls of the old page are invalid.
+
+The second event - PAGE\_CHANGED - is sent after the page has been changed and
+the program cannot veto it any more, it just informs it about the page change.
+
+To summarize, if the program is interested in validating the page values
+before allowing the user to change it, it should process the PAGE\_CHANGING
+event, otherwise PAGE\_CHANGED is probably enough. In any case, it is probably
+unnecessary to process both events at once.
 
 \wxheading{Derived from}
 
+\helpref{wxNotifyEvent}{wxnotifyevent}\\
 \helpref{wxCommandEvent}{wxcommandevent}\\
 \helpref{wxEvent}{wxevent}\\
 \helpref{wxEvtHandler}{wxevthandler}\\
@@ -37,7 +52,7 @@ Processes a wxEVT\_COMMAND\_NOTEBOOK\_PAGE\_CHANGING event.}
 \func{}{wxNotebookEvent}{\param{wxEventType}{ eventType = wxEVT\_NULL},
  \param{int}{ id = 0}, \param{int}{ sel = -1}, \param{int}{ oldSel = -1}}
 
-Constructor.
+Constructor (used internally by wxWindows only).
 
 \membersection{wxNotebookEvent::GetOldSelection}\label{wxnotebookeventgetoldselection}
 

docs/latex/wx/notifevt.tex

@@ -0,0 +1,52 @@
+\section{\class{wxNotifyEvent}}\label{wxnotifyevent}
+
+This class is not used by the event handlers by itself, but is a base class
+for other event classes (such as \helpref{wxNotebookEvent}{wxnotebookevent}).
+
+It (or an object of a derived class) is sent when the controls state is being
+changed and allows the program to \helpref{Veto()}{wxnotifyeventveto} this
+change if it wants to prevent it from happening.
+
+\wxheading{Derived from}
+
+\helpref{wxCommandEvent}{wxcommandevent}\\
+\helpref{wxEvent}{wxevent}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/event.h>
+
+\wxheading{Event table macros}
+
+None
+
+\wxheading{See also}
+
+\helpref{wxNotebookEvent}{wxnotebookevent}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxNotifyEvent::wxNotifyEvent}\label{wxnotifyeventconstr}
+
+\func{}{wxNotifyEvent}{\param{wxEventType}{ eventType = wxEVT\_NULL}, \param{int}{ id = 0}}
+
+Constructor (used internally by wxWindows only).
+
+\membersection{wxNotifyEvent::IsAllowed}\label{wxnotifyeventisallowed}
+
+\constfunc{bool}{IsAllowed}{\void}
+
+Returns TRUE if the change is allowed (\helpref{Veto()}{wxnotifyeventveto} 
+hasn't been called) or FALSE otherwise (if it was).
+
+\membersection{wxNotifyEvent::Veto}\label{wxnotifyeventveto}
+
+\func{void}{Veto}{\void}
+
+Prevents the change announced by this event from happening.
+
+It is in general a good idea to notify the user about the reasons for vetoing
+the change because otherwise the applications behaviour (which just refuses to
+do what the user wants) might be quite surprising.

include/wx/gtk/notebook.h

@@ -28,42 +28,6 @@ class wxImageList;
 class wxNotebook;
 class wxNotebookPage;
 
-// ----------------------------------------------------------------------------
-// notebook events
-// ----------------------------------------------------------------------------
-
-class wxNotebookEvent : public wxNotifyEvent
-{
-public:
-  wxNotebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0,
-                  int nSel = -1, int nOldSel = -1)
-  : wxNotifyEvent(commandType, id)
-  {
-      m_bAllow = TRUE;
-      m_nSel = nSel;
-      m_nOldSel = nOldSel;
-  }
-
-  // accessors
-  int GetSelection() const { return m_nSel; }
-  int GetOldSelection() const { return m_nOldSel; }
-
-  // for wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING event this method may be called
-  // to disallow the page change
-  void Veto() { m_bAllow = FALSE; }
-
-  // implementation: for wxNotebook usage only
-  bool Allowed() const { return m_bAllow; }
-
-private:
-  bool m_bAllow;
-
-  int m_nSel,     // currently selected page
-      m_nOldSel;  // previously selected page
-
-  DECLARE_DYNAMIC_CLASS(wxNotebookEvent)
-};
-
 //-----------------------------------------------------------------------------
 // wxNotebook
 //-----------------------------------------------------------------------------
@@ -186,28 +150,5 @@ public:
   DECLARE_EVENT_TABLE()
 };
 
-// ----------------------------------------------------------------------------
-// event macros
-// ----------------------------------------------------------------------------
-typedef void (wxEvtHandler::*wxNotebookEventFunction)(wxNotebookEvent&);
-
-#define EVT_NOTEBOOK_PAGE_CHANGED(id, fn)                                   \
-  {                                                                         \
-    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED,                                    \
-    id,                                                                     \
-    -1,                                                                     \
-    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
-    NULL                                                                    \
-  },
-
-#define EVT_NOTEBOOK_PAGE_CHANGING(id, fn)                                  \
-  {                                                                         \
-    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING,                                   \
-    id,                                                                     \
-    -1,                                                                     \
-    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
-    NULL                                                                    \
-  },
-
 #endif
     // __GTKNOTEBOOKH__

include/wx/gtk1/notebook.h

@@ -28,42 +28,6 @@ class wxImageList;
 class wxNotebook;
 class wxNotebookPage;
 
-// ----------------------------------------------------------------------------
-// notebook events
-// ----------------------------------------------------------------------------
-
-class wxNotebookEvent : public wxNotifyEvent
-{
-public:
-  wxNotebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0,
-                  int nSel = -1, int nOldSel = -1)
-  : wxNotifyEvent(commandType, id)
-  {
-      m_bAllow = TRUE;
-      m_nSel = nSel;
-      m_nOldSel = nOldSel;
-  }
-
-  // accessors
-  int GetSelection() const { return m_nSel; }
-  int GetOldSelection() const { return m_nOldSel; }
-
-  // for wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING event this method may be called
-  // to disallow the page change
-  void Veto() { m_bAllow = FALSE; }
-
-  // implementation: for wxNotebook usage only
-  bool Allowed() const { return m_bAllow; }
-
-private:
-  bool m_bAllow;
-
-  int m_nSel,     // currently selected page
-      m_nOldSel;  // previously selected page
-
-  DECLARE_DYNAMIC_CLASS(wxNotebookEvent)
-};
-
 //-----------------------------------------------------------------------------
 // wxNotebook
 //-----------------------------------------------------------------------------
@@ -186,28 +150,5 @@ public:
   DECLARE_EVENT_TABLE()
 };
 
-// ----------------------------------------------------------------------------
-// event macros
-// ----------------------------------------------------------------------------
-typedef void (wxEvtHandler::*wxNotebookEventFunction)(wxNotebookEvent&);
-
-#define EVT_NOTEBOOK_PAGE_CHANGED(id, fn)                                   \
-  {                                                                         \
-    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED,                                    \
-    id,                                                                     \
-    -1,                                                                     \
-    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
-    NULL                                                                    \
-  },
-
-#define EVT_NOTEBOOK_PAGE_CHANGING(id, fn)                                  \
-  {                                                                         \
-    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING,                                   \
-    id,                                                                     \
-    -1,                                                                     \
-    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
-    NULL                                                                    \
-  },
-
 #endif
     // __GTKNOTEBOOKH__

include/wx/msw/notebook.h

@@ -41,40 +41,11 @@ WX_DEFINE_ARRAY(wxNotebookPage *, wxArrayPages);
 #undef  WXDLLEXPORTLOCAL
 #define WXDLLEXPORTLOCAL
 
-// ----------------------------------------------------------------------------
-// notebook events
-// ----------------------------------------------------------------------------
-class WXDLLEXPORT wxNotebookEvent : public wxNotifyEvent
-{
-public:
-  wxNotebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0,
-                  int nSel = -1, int nOldSel = -1)
-  : wxNotifyEvent(commandType, id)
-  {
-      m_nSel = nSel;
-      m_nOldSel = nOldSel;
-  }
-
-  // accessors
-    // the currently selected page (-1 if none)
-  int GetSelection() const { return m_nSel; }
-  void SetSelection(int nSel) { m_nSel = nSel; }
-    // the page that was selected before the change (-1 if none)
-  int GetOldSelection() const { return m_nOldSel; }
-  void SetOldSelection(int nOldSel) { m_nOldSel = nOldSel; }
-
-private:
-  int m_nSel,     // currently selected page
-      m_nOldSel;  // previously selected page
-
-  DECLARE_DYNAMIC_CLASS(wxNotebookEvent)
-};
-
 // ----------------------------------------------------------------------------
 // wxNotebook
 // ----------------------------------------------------------------------------
 
-// @@@ this class should really derive from wxTabCtrl, but the interface is not
+// FIXME this class should really derive from wxTabCtrl, but the interface is not
 //       exactly the same, so I can't do it right now and instead we reimplement
 //       part of wxTabCtrl here
 class WXDLLEXPORT wxNotebook : public wxControl
@@ -199,27 +170,4 @@ protected:
   DECLARE_EVENT_TABLE()
 };
 
-// ----------------------------------------------------------------------------
-// event macros
-// ----------------------------------------------------------------------------
-typedef void (wxEvtHandler::*wxNotebookEventFunction)(wxNotebookEvent&);
-
-#define EVT_NOTEBOOK_PAGE_CHANGED(id, fn)                                   \
-  {                                                                         \
-    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED,                                    \
-    id,                                                                     \
-    -1,                                                                     \
-    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
-    NULL                                                                    \
-  },
-
-#define EVT_NOTEBOOK_PAGE_CHANGING(id, fn)                                  \
-  {                                                                         \
-    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING,                                   \
-    id,                                                                     \
-    -1,                                                                     \
-    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
-    NULL                                                                    \
-  },
-
 #endif // _NOTEBOOK_H

include/wx/notebook.h

@@ -1,6 +1,70 @@
 #ifndef _WX_NOTEBOOK_H_BASE_
 #define _WX_NOTEBOOK_H_BASE_
 
+// ----------------------------------------------------------------------------
+// headers
+// ----------------------------------------------------------------------------
+
+#include "wx/event.h"   // the base class: wxNotifyEvent
+
+// ----------------------------------------------------------------------------
+// notebook event class (used by NOTEBOOK_PAGE_CHANGED/ING events)
+// ----------------------------------------------------------------------------
+
+class WXDLLEXPORT wxNotebookEvent : public wxNotifyEvent
+{
+public:
+    wxNotebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0,
+                    int nSel = -1, int nOldSel = -1)
+        : wxNotifyEvent(commandType, id)
+        {
+            m_nSel = nSel;
+            m_nOldSel = nOldSel;
+        }
+
+    // accessors
+        // the currently selected page (-1 if none)
+    int GetSelection() const { return m_nSel; }
+    void SetSelection(int nSel) { m_nSel = nSel; }
+        // the page that was selected before the change (-1 if none)
+    int GetOldSelection() const { return m_nOldSel; }
+    void SetOldSelection(int nOldSel) { m_nOldSel = nOldSel; }
+
+private:
+    int m_nSel,     // currently selected page
+        m_nOldSel;  // previously selected page
+
+    DECLARE_DYNAMIC_CLASS(wxNotebookEvent)
+};
+
+// ----------------------------------------------------------------------------
+// event macros
+// ----------------------------------------------------------------------------
+
+typedef void (wxEvtHandler::*wxNotebookEventFunction)(wxNotebookEvent&);
+
+#define EVT_NOTEBOOK_PAGE_CHANGED(id, fn)                                   \
+  {                                                                         \
+    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED,                                    \
+    id,                                                                     \
+    -1,                                                                     \
+    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
+    NULL                                                                    \
+  },
+
+#define EVT_NOTEBOOK_PAGE_CHANGING(id, fn)                                  \
+  {                                                                         \
+    wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING,                                   \
+    id,                                                                     \
+    -1,                                                                     \
+    (wxObjectEventFunction)(wxEventFunction)(wxNotebookEventFunction) &fn,  \
+    NULL                                                                    \
+  },
+
+// ----------------------------------------------------------------------------
+// wxNotebook class itself
+// ----------------------------------------------------------------------------
+
 #if defined(__WXMSW__)
 #ifdef __WIN16__
   #include  "wx/generic/notebook.h"

samples/controls/controls.cpp

@@ -99,6 +99,7 @@ public:
     void OnRadioButtons( wxCommandEvent &event );
     void OnSetFont( wxCommandEvent &event );
     void OnPageChanged( wxNotebookEvent &event );
+    void OnPageChanging( wxNotebookEvent &event );
     void OnSliderUpdate( wxCommandEvent &event );
 #ifndef __WIN16__
     void OnSpinUpdate( wxSpinEvent &event );
@@ -455,6 +456,7 @@ const int  ID_SPIN              = 182;
 
 BEGIN_EVENT_TABLE(MyPanel, wxPanel)
 EVT_SIZE      (                         MyPanel::OnSize)
+EVT_NOTEBOOK_PAGE_CHANGING(ID_NOTEBOOK, MyPanel::OnPageChanging)
 EVT_NOTEBOOK_PAGE_CHANGED(ID_NOTEBOOK,  MyPanel::OnPageChanged)
 EVT_LISTBOX   (ID_LISTBOX,              MyPanel::OnListBox)
 EVT_LISTBOX_DCLICK(ID_LISTBOX,          MyPanel::OnListBoxDoubleClick)
@@ -506,7 +508,7 @@ MyPanel::MyPanel( wxFrame *frame, int x, int y, int w, int h )
     m_text = new wxTextCtrl( this, -1, "This is the log window.\n", wxPoint(0,50), wxSize(100,50), wxTE_MULTILINE );
     //  m_text->SetBackgroundColour("wheat");
 
-    delete wxLog::SetActiveTarget(new wxLogTextCtrl(m_text));
+    delete wxLog::SetActiveTarget(new wxLogStderr);
 
     m_notebook = new wxNotebook( this, ID_NOTEBOOK, wxPoint(0,0), wxSize(200,150) );
 
@@ -818,6 +820,26 @@ void MyPanel::OnSize( wxSizeEvent& WXUNUSED(event) )
     if (m_text) m_text->SetSize( 2, y*2/3+2, x-4, y/3-4 );
 }
 
+void MyPanel::OnPageChanging( wxNotebookEvent &event )
+{
+    int selNew = event.GetSelection(),
+        selOld = event.GetOldSelection();
+    if ( selOld == 2 && selNew == 4 )
+    {
+        wxMessageBox("This demonstrates how a program may prevent the "
+                     "page change from taking place - the current page will "
+                     "stay the third one", "Conntrol sample",
+                     wxICON_INFORMATION | wxOK);
+
+        event.Veto();
+    }
+    else
+    {
+        *m_text << "Notebook selection is being changed from "
+                << selOld << " to " << selNew << "\n";
+    }
+}
+
 void MyPanel::OnPageChanged( wxNotebookEvent &event )
 {
     *m_text << "Notebook selection is " << event.GetSelection() << "\n";